Tips for Successful Open Source Documentation

by Ben Pearson

February 3rd, 2015

This short talk from Raghavendra Prabhu gives some pointers on how to successfully leverage documentation in an open source community.

[00:30] – Good documentation helps communities grow, attracts contributors, enhances the quality of code, and helps make bug fixes. Redis, Docker, the Linux Kernel, Python and Go are just a few examples of projects with good documentation.

[4:30] – There are multiple management formats you can choose from that each have an effect on the quality of documentation. Tools like Doxygen, Sphinx, pandoc, and Haddock, can make management easier.

[6:00] – Proper attribution mechanisms are also important because they provide incentives and feedback loops to people who help document.

[7:00] Blog posts can be a good way to make certain documentation less mechanical and more like a tutorial that is given directly to the reader.

[9:30] – A dialectical approach (FAQ) can help with areas that need more of a human flow of thinking. This is good for troubleshooting, beginners, or ‘learning the hard way.’

[11:00] – Examples and patterns are some of the quickest ways for people to learn new materials. It’s good for documentation to include samples.

[12:31] – Documentation needs to be designed for both end users and developers.