Writing great documentation: technical style

http://jacobian.org/writing/great-documentation/technical-style/

by jacobian • 17 years ago

78 15 17 years ago

patio11• 17 years ago

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.

blasdel• 17 years ago

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 and with default styles is worse than useless, just use and , they aren't poisonous. I did appreciate the as yellow-highliter fad that 37signals kicked off years ago.

weeksie2• 17 years ago

Actually, the commas inside the quotation marks is an American English thing. Regardless of logic it's completely consistent with usage in the States. In the UK it's not.

That said, where to place the commas, full stops, and semi-colons is pretty tricky no matter what side of the Atlantic you're on.

youngian• 17 years ago

I have particular qualms with this in technical documentation. For example, I'll often be talking about a string or command and put it inside quotes to make clear what is part of the string or command. If that's at the end of the sentence, the rules dictate my period should go inside the quotes as well. I can never bring myself to obey that.

greyman• 17 years ago

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.

RyanMcGreal2• 17 years ago

I think a lot of people misunderstand the "omit needless words" rule. If you've taken out so many words that the text is no longer easy to read, that means you actually need some of the words you've omitted. :)

jokull• 17 years ago

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.

Adrock• 17 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.

RyanMcGreal2• 17 years ago

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.

jriddycuz• 17 years ago

My solution: drop it's in favor of the antiquated (or timeless) 'tis. Do this in speech too to give your elocution style a bit of the whimsical and refined air of an older time. ;)

mhb• 17 years ago

Jerry Pournelle on writing:

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

tel• 17 years ago

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.

tptacek• 17 years ago

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.

billswift• 17 years ago

That's the book commonly recommended on Language Log (http://languagelog.ldc.upenn.edu/nll/) also. Geoffrey K. Pullum there is highly critical of Strunk and White.

Writing great documentation: technical style

Related Stories