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.
- [13:30] – Further reading.
