Doc Like an Egyptian

Speaker

Level: 
Intermediate
Slides: 

Every software project needs good documentation--otherwise, how will users know how to use the software and developers know how to contribute code to the project? But creating and maintaining documentation is hard! Software versions change, new features are added (and old ones deprecated), formats change, and search engines seem to point users to everything but the correct docs.

This presentation discusses the common gotchas associated with maintaining documentation and the pros and cons of some of the available open source solutions. It then provides an overview of Sphinx, an open source documentation generation system which provides git integration, pootle integration (for translations), multiple output formats, and an easy-to-learn formatting language. It also discusses some of the tips and tricks learned from converting the PC-BSD, FreeNAS, and Lumina documentation projects to Sphinx.