Conference Schedule

Track one or two? Eeenie, meenie, miney, moe…

log in to bookmark.

RTFM -- wRite The Friendly Manual

A Talk presented by James Bennett


Thursday, September 8th 2:20 p.m.–3 p.m.




An introduction to writing great documentation. Not just in the "here's some tools and how to use them" sense, but in the "here's why you should care about documentation" sense and the "how to write things people will read" sense.


Sections 1-3 are intended to be short but sweet, introducing a few essential topics to set the stage for what comes after. Section 4 is where the real meat begins, covering some basic principles of actual writing. Sections 5-6 return to technical matters, with most of the focus being on overviews rather than in-depth tutorials on specific tools or services.

  1. The two kinds of documentation
    1. Documentation for people who will hack on your code
    2. Documentation for people will run your code
    3. Why you need both!
    4. Support mechanisms
  2. The other two kinds of documentation
    1. Hand-written explanations
    2. Auto-generated API references
    3. Why you need both!
    4. Support mechanisms
  3. The mindset
    1. DDD -- Documentation-Driven Development
    2. Write documentation before code
    3. Documentation as specification
  4. The style
    1. "Raise your hand if you have a liberal-arts degree"
    2. A whirlwind tour of good prose
    3. Be friendly!
    4. Writing to your audience
    5. How to write a how-to
  5. The tools
    1. reST
    2. Sphinx
    3. pydoc/epydoc/etc.
    4. Django!
  6. The rest
    1. What your file layout should look like
    2. Magical distutils incantations
    3. Hosting
      1. On your own
      2. On
      3. On readthedocs
      4. Other options
    4. Feedback
      1. Why "documentation" is a component in your issue tracker
      2. How to handle suggestions gracefully
  7. Questions?