Sessions at DjangoCon US 2011 about Documentation on Thursday 8th September

Your current filters are…

  • RTFM -- wRite The Friendly Manual

    by James Bennett

    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.

    - 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

    - The other two kinds of documentation
    1. Hand-written explanations
    2. Auto-generated API references
    3. Why you need both!
    4. Support mechanisms

    - The mindset
    1. DDD - Document-Driven Development
    2. Write documentation before code
    3. Documentation as specification

    - 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

    - The tools
    1. reST
    2. Sphinx
    3. pydoc/epydoc/etc.
    4. Django!

    - The rest
    1. What your file layout should look like
    2. Magical distutils incantations
    3. Hosting
    - on your own
    - on packages.python.org
    - on readthedocs
    - other options

    - Feedback
    1. Why "documentation" is a component in your issue tracker
    2. How to handle suggestions gracefully

    - Questions

    At 2:20pm to 3:00pm, Thursday 8th September

    Coverage video