Writing great documentation
log in to bookmark this presentaton
Novice / Talk
March 12th 11:05 a.m. – 11:35 a.m.
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, Epydoc, 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.