Writing great documentation
I love Django’s documentation. It clocks in at about 700 pages printed, and most of it is clear, concise, and helpful. I think Django’s among the best documented open source projects, and nothing makes me prouder.
If any part of Django endures, I hope it’ll be a sort of “documentation culture” — an ethos that values great, well-written documentation. To that end, I’m writing a series of articles laying out the tools, tips, and techniques I’ve learned over the years I’ve spent helping to write Django’s docs.
This advice will mostly be targeted towards those documenting libraries or frameworks intended for use by other developers, but much of it probably applies to any for of technical documentation.
Entries in this series:
What to write
Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation. This is the first in a series of posts that’ll cover the art of writing good technical documentation.
How to develop a great technical writing style.
You need an editor
If you really want to produce great documentation, it needs to be edited.