Writing great documentation: technical style

This is, in general, an awesome article.

The one thing I'd add is that, unlike most newspaper articles, technical documentation can be executable. I was so excited when I realized the implications of that I nearly had to sit down. (Yes, I live a boring life.)

I did a bit of that with the documentation to A/Bingo: the documentation is presented in a live demo, the formatted sample code is automatically composed from what I'm actually running (and thus gets automatically patched without me having to do anything special about it), and I copiously abuse my favorite Javascript effects (lightboxes, etc) to make the presentation flow better that linear text.

For example, often in tech documentation you want to focus attention on a portion of the code buried in a bunch of boilerplate. (Or maybe that is just those of us who write Java all day.) You can bold the bits you want to emphasize, or you can hide the boring details with Javascript and let only those folks who need them look them up.

My opinion is this is better than linking to a fuller version on another page, as it interrupts the user's flow less. It is also more readable than a few lines of bold text studded in the boilerplate, and more usable than omitting the boilerplate and producing code which doesn't function if copy/pasted.

I'm really surprised you didn't stress the importance of having useful fragment identifiers for every section, and using references to them liberally -- and not just the obvious <a href="#foo">foo</a> -- tertiary links inline in prose like Suck.com popularized in the olden times.

Some nitpicks:

and you need to understand why I’m putting the commas and semicolons in this sentence inside the quotes, not outside

I know why you do that, but it doesn't make it any less bullshit. It's not like you're doublestriking on a monospaced typewriter or manually kerning on a press! Don't pollute what are ostensibly quotes with exterior punctuation. At least you're using the oxford comma :)

Mostly, this means using emphasis and strong text frequently. I usually avoid too much strong because it’s looks like I’m just aping Jakob Neilsen, but whatever.

An apter and and more pejorative example for today's whippersnapper would be Jeff Atwood. In my opinion using <em> and <strong> with default styles is worse than useless, just use <i> and <b>, they aren't poisonous. I did appreciate the <em> as yellow-highliter fad that 37signals kicked off years ago.

One written tic I have in my technical writing is to use the adverb "simply" before an instruction.  It was pointed out to me early in my career that this is worse than noise... it can make the reader feel bad or annoyed if they don't succeed or perceive it as simple.  I now always make a second pass to remove any potentially condescing phrases.

I'd like to comment the rule of "omit needless words". Generally I agree with that, but if it is applied rigorously across the whole article, I find it quite difficult to read, despite each sentence being logical and clear. It just needs a greater concentration then, like in this very article - I was tired after reading it (English is not my mother language).

I prefer Mark Pilgrim's diveinto____ style, where the text has more "space" and feels lighter. In my opinion, it is not always better to make the sentence shorter.

One thing I'd emphasize is that all writers begin with imitation. It's how the human brain learns new things and so you might as well abuse that.

Find a writer whose style you admire. Figure out why. Practice, practice, practice. But realize that until you're speaking with your own voice you haven't even begun to yet walk.

Documentation should draw out, using good language, the exciting bits. It gives you a feel for what a piece of software does especially well. When a developer commits an awesome feature that should be reflected in the documentation.

Jacob's a good writer, and I'm not surprised that Django is so well-documented. I just have one small quibble with this piece:

> You need to understand the difference between "its" and "it’s";

If the problem is that people conflate "its" and "it's", the solution is not to keep placing them side-by-side.

What got me to stop mistaking the one for the other was to understand "its" not in opposition to "it's", but as part of the set of possessive pronouns: "my", "your", "his", "her", "its", "their". Note that none of these pronouns have an apostrophe.

Jerry Pournelle on writing:

http://www.jerrypournelle.com/slowchange/myjob.html

A hacker-friendly book on style is _Style: Toward Clarity and Grace_. I picked it up off a recommendation on Richard Gabriel's site. _Style_ breaks down the different aspects of "good" writing as if they were features, and refactors prose to gain those features.