Bookmark and Share

Creating great documentation with Sphinx

Programmers often consider documenting their software a boring task, and the result unfortunately speaks for itself. Documentation tends to be poorly written, inconsistently structured and simply bad from the beginning, and soon decays into plain disinformation as nobody is interested in maintaining it. There always seem to be more important things to do, such as maintaining the software itself. Fair enough; programmers are programmers, not technical writers. But then, abusing programmers as technical writers is often inevitable if there are no resources to hire actual writers. After all, creators of the software may be the only ones who actually know how it’s supposed to work.

However, a lot can be saved by using proper tools. Microsoft Word isn’t a proper tool for documenting software. Instead, enter Sphinx. It’s a documentation generator, converting a bunch of reStructuredText files into HTML websites and other formats such as PDF. It’s being used to document major projects such as the Python programming language—you know, the one that Google, NASA and YouTube build on—so it’s likely adequate for your project too. It can’t turn bad writing into great manuals, but it can promote good habits, which in turn results in less sucky documentation. By good habits I mean, for example:

  • Considering the documentation to be an integral part of the software. This means storing the (sources for the) documentation alongside with the software sources in a version control system. If the documentation isn’t in the central repository, it doesn’t exist.

  • Automatically generating as much of the boilerplate and repeated stuff as possible. Humans suck at doing boring, repetitive tasks consistently. Computers excel at it. Let the machine do the boring stuff.

  • Working with a text editor (such as Sublime Text), concentrating on the text and structure and letting the machine take care of mechanical issues such as formatting. Save the scarce resource—your brainpower—for the essential.

These may seem like small things, nitpicking. Maybe so, but it’s also possible that these small things make all the difference in the end. If programmers feel good about writing documentation, they’ll likely be motivated and spend more effort doing it, and as a result, the documentation is better. Way better, I believe.

Installing Sphinx to Windows

Install MiKTeX if you want to create PDF files, Python to be able to run Sphinx, and setuptools for easy install. Then, from the command line:

easy_install -U Sphinx

That’s it! From here you can proceed as instructed in the Sphinx tutorial.

Installing to Sphinx Debian/Ubuntu

Install packages texlive-latex-extra and python-setuptools. The former provides the needed pdflatex stuff to generate PDF files, and the latter provides the easy_install program to install Sphinx itself. Then:

easy_install -U Sphinx

That’s it! From here you can proceed as instructed in the Sphinx tutorial.

About writing

A good reference to see how to structure a bigger Sphinx project is The Definitive Guide to Jython. The whole source is available at http://bitbucket.org/javajuneau/jythonbook/.

For the writing process itself, check out the Writing great documentation series by Jacob Kaplan-Moss (maintainer of the Django project—“The Web framework for perfectionists with deadlines”—whose documentation is incidentally created with Sphinx).

Last modified: 2010-11-07 19:05 +0200


blog comments powered by Disqus