Many words have been written on community building, engagement, and retention. The discussion around community management is alive and kicking, with articles and blog posts everywhere about how to grow, support, and not mess up open source communities.
As I mentioned in my previous articles about content strategy and DevOps for documentation, quality content is tip-toeing to the front lines as something that's not only valuable for users, but to contributors as well. If good docs can help new users learn your software, it can help new contributors to get involved with your project, right?
Right. Except that when crunch time comes, all the content strategy and DevOps won't help your project docs if the community doesn't participate. When a few developers get tired of something not working properly, or get excited about making something new, they storm the castle and make it happen. But somehow, the How to Storm a Castle tutorial is nowhere to be found.
To document or not to document?
How many developers have said these (or similar) words when faced with this question?
"I don't have time to document this."
"It's self-documenting."
Fast-forward a few weeks or months later...
"This code has no documentation!"
"What does this code even do?"
"I should have documented this..."
You're not alone. Words are work. Sometimes they're harder work than code, since they don't neatly compile into binaries. But they're not as hard as you think.
Help your community help itself
There are many ways to improve community docs, and there's something for everyone in the project to do, no matter their role or experience level. Whether your project is just taking shape and form or has been running for years, taking the time to improve the way contributors write and publish docs can mean that your contributors can follow this process more independently and easily.
The main thing to remember is that the efforts need to be collaborative, scalable, and simple. I will now attempt to describe some examples of activities I have seen or have been involved with from open source communities that aim to increase engagement of open source projects in better docs and bridge the knowledge gap between writers and engineers.
Documentation guidelines
If code contribution guidelines are meant to help developers get started and adhere to standards, doc contribution guidelines serve the same purpose. Documentation guidelines can encompass style conventions, procedures on how to submit doc patches, and which code contributions require documentation.
The only prerequisite for contributing to doc guidelines is to successfully contribute something. Next time you tackle a doc task in your project, why not write some notes or suggestions and share them with the community? Merely starting a discussion about the optimal way to integrate docs into your project will remind folks that this is a topic worth discussing.
Need inspiration? Check out projects like Django, OpenStack, KDE, and ArchLinux for some examples of documentation guidelines.
And remember that doc commits are generally lower risk than code commits. You should simplify the process as much as you can, and remember to keep the instructions clear and concise; if I need to create three different user accounts and get four different karma points just to fix a typo, you're going to disengage me faster than you can say "Gerrit".
Templates
Templates are great for standardized or modular documentation. Take the README file, for example. Every open source project starts with a README file, which makes it an extremely visible and an important first-impression document.
Among the Pythonistas, the Read the Docs README template has been the go-to standard for quite some time. The Drupal project also has a README template with section descriptions, and the Fedora documentation team has been working on a documentation cookbook with topic "recipes", which not only describe how to contribute docs and writing guidelines, but can be used as templates themselves.
No time to make a template? How about some examples instead! You can select a topic or content file that you feel represents a good structure and format, and include it in your shiny new documentation guidelines as an example. Anyone who wishes to contribute can look at the source file and at least get the basic idea of how to structure a topic and which sections should be included.
Doc sprints, hackfests, and workshops
As a writer, these are probably my favorite activities, because they involve direct interaction with the open source project and often lead to immediate and repeatable results. Combining the deep-dive knowledge of the developers and the holistic approach to software of a technical writer can lead to really valuable insights about not just the documentation, but the overall usability of the project.
I've had the pleasure of sprinting alongside projects like Fedora and NixOS, as well as running a documentation workshop for KDE (past) and Django (future). These sprints and workshop helped me learn the inner workings of open source documentation and, in the case of NixOS, for example, led to an complete restructuring of the source files in three out of the four major manuals as well as a new content contribution procedure.
Doc sprints are also a great way to introduce new contributors to your project, and newcomers to open source in general. In every Django Girls workshop that I was involved with I made sure to include a follow-up doc sprint for the tutorial, organizer manual, and any other resource for the program. It's a great way to introduce newcomers to real-life GitHub contribution workflow while improving the docs at the same time!
Help desks and booths
Recently I was honored to lead the first ever (I think? somebody please correct me if I'm wrong) documentation help desk at a developer conference, the conference being EuroPython 2015. I teamed up with Paul Roeland and Maciej Szlosarczyk as we put on our doc(tor)s hats and robes and opened a pop-up documentation clinic for all your ailing open source documentation needs.
During our three-hour-turned-four-hour session, we consulted with people from about 15-20 projects who had really interesting problems and questions, such as how to restructure their doc set, create a migration plan from traditional word-processing software to markup languages and source control, or even restructuring the project website to make the docs more accessibly to visitors.
As an added bonus, we got to reinforce and further integrate the documentation discussion into the developer community. During the following conference days, we kept hearing from conference attendees who missed the session or didn't know about it how sorry they were because they could have used our help. Maybe a documentation booth or help desk could be a new tradition at developer events?
Documentation talks in developer events
A writer gives a documentation talk at a developer conference. Not the beginning of a bad joke, but something that I'm happy to see an increase in and would like to see more of. A developer giving a documentation talk at a developer conference is also quite acceptable and encouraged, of course; the important thing is to present your topics in a way that appeals to a developer audience.
Doc talks at conference might not seem attractive at first to developer attendees, but they are a great way to condense information and pitch ideas to, at the very least, get the developers to think about docs in a different way. My current favorite talk to give is FOSS DOCS 101, because it covers high-level concepts and aims to engage open source developers in doc efforts.
Documentation events
Long gone are the days where TechComm conferences boasted 12 talks about single-sourcing and not a single developer could be spotted on-site. A new generation of documentation communities is gaining traction, thanks to the open source philosophy of grassroots collaboration and brave experimentation.
Write the Docs, which I am proudly involved with, started a little over two years ago in Portland, Oregon as a one-off event, and since then spread to encompass a two international conferences as well as countless meetups all over the U.S. Its mission: to integrate, not segregate, documentation into the broader tech community by creating a space where all tech roles are welcome to discuss anything related to content. In fact, more than 50% of the attendees at their conferences are not writers, and represent many open source technologies and communities.
Another yearly event well worth mentioning is Open Help, which focuses more on sprints and open discussions. Open Help invites all open source projects to gather and brainstorm, hack, and collaborate on their content, and laces the event with pre-selected presentations to spark discussions and inspire the attendees. And no, you don't have to be a writer to attend this event either. The only prerequisite is to care about content and about open source.
Spark the change, encourage collaboration
All these ideas I'm talking about are useless if nobody puts them into practice. There's only so much that one person can do, so I am calling you, developers and writers alike, to reach out and create a collaborative environment.
If you're a writer, don't be afraid to submit a doc presentation, sprint, or workshop to a developer event. You have expertise to share, and the developers will be happy to learn from your experience. I've seen the attitude toward doc folks in developer conferences, meetups, and sprints improve since I first ventured into the world of open source, and it's thanks to the open discussion that us writers can do our part in bridging the knowledge and engagement gap.
If you're a developer, reach out to doc folks and invite them to your conferences, sprint, and meetups. Attend a documentation event and learn about how writers think, work, and do community. Everyone can benefit from quality content, and you'll be surprised how happy writers will be to share the knowledge we've accumulated and to help out with open source docs. We walk among you, all you need to do is reach out.
Dish
This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.
1 Comment