Series: Writing Great Documentation

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.

What to write November 10th, 2009 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. At a high level, you can break down the different types of documentation you need to provide into three different formats:…

Technical style November 11th, 2009 Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation. Learn to write Unfortunately, there aren’t any shortcuts here. The best way to learn how to write great documentation is to first learn how to write (anything). There are some important differences between technical documentation and your average prose, but a solid foundation of good written communication skills is an irreplaceable prerequisite.…