The Salt Docs community working group at Salt Project aimed to boost community engagement and enhance our documentation through a series of one-day documentation jams. However, our first documentation jam the previous year had low attendance and didn't yield significant results. In our group retrospective for the event, we realized that for the next event to succeed, it needed several important ingredients:

• Intrinsic motivation - The event needed to accomplish something that mattered and was meaningful to participants.
• Task-orientation - The event needed to focus on getting a specific project done. It needed to be granular so that anyone could easily pick up a task and work on it. And it needed to be modular, with discrete components of work that could easily fit back into one larger whole.
• Low coordination costs - The logistical structure of the event needed to reduce coordination costs and provide users with lots of onboarding support so that they could succeed on their own. This ensured that the docs jam leaders could focus on the most important needs during the day.

From these insights, we decided the event should focus on creating a high-quality getting started guide for new users. We obtained permission to organize an event around converting a previously internal guide for customers into open-source documentation, making the new guide freely accessible to everyone.

After announcing the doc jam project at SaltConf20, our documentation working group spent four months preparing for the event. We first obtained permission from internal copyright holders and original authors to open source a previous guide. We also coordinated with Salt experts to review and refine the content, ensuring accuracy and public accessibility.

One of the most crucial steps was working out the logistical flow of the event. We thought carefully about the contributor experience and created several important supporting documents to guide participants through the event. These documents were crucial for minimizing coordination costs and enabling participants to work independently. We then stress-tested the end-to-end contributing process ourself to make sure that all the logistics worked well.

We also created an effective publicity campaign with messages tailored to two demographics we wanted to attract to our project: existing Salt users and technical writers. Our messaging not only provided event details, but also explained the intrinsic and extrinsic benefits of participating from the point of view of those two groups. We then publicized our event in channels where those two groups of people tended to congregate.

On the day of the docs jam, we dedicated the morning to helping participants set up their environments. After a midday keynote featuring Salt Founder Tom Hatch, the participants began working on their tasks, co-working on the Zoom call and receiving real-time support. The documentation jam wrapped up later that evening as we finished accepting all the merge requests from the event.

The community documentation jam was a huge success from every possible metric. The event had:

• High attendance and participation: 35 attendees
• Excellent diversity levels from participants: a 50-50 gender split with contributors from all continents
• Impressive conversion rates: 3 new contributors turned into long-term documentation working group members
• A perfect productivity score: all 17 chapters of the guide were successfully converted in one day

Participating community members gave glowing reviews in later community meetings. One of our community members who participated said: “What I thought was especially great was getting one-on-one help setting up an environment. This is the kind of thing people attend courses and pay money for, so it was a huge value to contributors.”

For about two weeks after the event, I received at least one inquiry a day asking when we would hold another docs jam event like this one. To this day, I am told regularly that this user guide is one of the most helpful tools for new members onboarding with the project.

The dirty secret is that, in the amount of time we spent preparing for the documentation jam, we could have probably just converted all the content files ourselves. But we chose to invest our time building this infrastructure as an investment in our larger community. Events like these breathe new life and energy into the project by engaging new and existing community members. These events also open up opportunities to give back to the community through mentorship and one-on-one engagement. For that reason, I consider this event to be one of the all-time highlights of my career.