Jacob Kaplan-Moss

Writing great documentation

Writing great documentation

Presented by Jacob Kaplan-Moss

Django’s among the best documented open source projects; I'm intensely
proud of that accomplishment. If any part of Django endures, I hope
it’ll be a “documentation culture” — an ethos that values great,
well-written documentation. To that end, this talk looks at the tools,
tips, and techniques I’ve learned over the years. I hope it helps you
write great documentation, too.

Abstract

This talk looks at tips, tools, and techniques you can use to produce
great technical documentation.

It's split roughly into two parts:

- Part 1: technique. We'll look at the structural elements that make
documentation useful: tutorials, high-level overviews, topical
guides, reference material, FAQs, and more. We'll cover some tips on
how to get documentation done, and community processes for handling
documentation in teams (open or not). We'll also talk about what I'm
calling "Documentation Driven Development" - a technique riffing off
Test Driven Development that calls for writing documentation before
code.
- Part 2: tools. Over the last couple of years a few fantastic tools
have sprung up that ease the technical aspects of writing
documentation. We'll talk about which tools are suitable for which
uses, and look at a handful of cool tools including
`Sphinx <http://sphinx.pocoo.org/>`__,
`Epydoc <http://epydoc.sourceforge.net/>`__, and
http://fitzgen.github.com/pycco/.

This talk is mostly targeted towards those documenting libraries or
frameworks intended for use by other developers, but much of it probably
applies to any sort of technical documentation.