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.
Series: Writing Great Documentation
Writing Great Documentation: You need an editor
I’m supposed to be this expert on writing, right? So how come my previous articles have had so many errors?
Simple: my blog doesn’t have an editor.
That’s typical for a blog, but it’s unfortunately also typical of open source documentation: the vast majority of technical documentation doesn’t reach far beyond rough draft status.
All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass.
Writing Great Documentation: Technical style
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.
Writing Great Documentation: 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.
At a high level, you can break down the different types of documentation you need to provide into three different formats:
November 10th, 2009
•
documentation
writing