Open source documentation — What can we do to improve it
Open source products have their own community, and the individuals from the community contribute to the product. Therefore, it is important that open source products get documentation right. Don’t you agree? :)
Contributors don’t want to contribute to a product that they can not understand.
A surprising fact: The biggest complaint based on the GitHub Open source Survey 2017 was incomplete or confusing documentation.
“Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities.”
We are ending 2018 now (hooray it’s almost Christmas) .. and I hope that open source documentation has improved over the year (fingers crossed).
How can we improve our open source documentation?
Like any other project, it starts from the very beginning. Let’s take a look at the content release cycle
Plan and write:
Make sure you identify your end-users. At the beginning of a release, plan not only the documentation and training content for each new feature but also what would work best as technical articles, blog posts, or marketing content.
You can come up with innovative ways to present content and help users try out samples easily. For example, I used Swagger REST API documentation to help users try out the API documentation.
It is important to remember that open source products have wider audiences, many of whom are non-native English speakers. Therefore, use clear, concise language and include a glossary of terms. (The technical terms I am familiar with might not be familiar to another user.)
Always remember to write assuming the user is new to the product or feature. Imagine that the user has the same curiosity level as you have when configuring the product. Therefore, always try to answer the question WHY when writing content.
Test and review
Once the content is written you need to ensure that the documented content is tested. If the steps you listed down is incorrect it is not going to help the user. Therefore, you need to seriously consider testing your content for accuracy (else, your content is useless.. might as well not have the content out there :D).
Make sure you get your content reviewed by another writer. It is amazing what an extra pair of eyes can do to improve your content further (speaking from experience.. so try it out).
Get feedback from the community
Once you have written, tested, and reviewed the content, you are ready to release the content. Now, you need to be prepared to gather feedback from the community and improve the documentation.
There are many ways to gather feedback from the community. Git issues, JIRAs, Slack, Stack Overflow, direct customer feedback, and much more. Whatever your mechanism may be, make sure to let your community know on how they can contribute to your documentation. If you don’t tell them, they are not going to know how to do it and your documentation is not going to improve over time.
Therefore, it is your responsibility to help the community engage.
