Writing great documentation: technical style(jacobian.org)
jacobian.org
Writing great documentation: technical style
http://jacobian.org/writing/great-documentation/technical-style/
15 comments
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.
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.
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.
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.
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.
I can understand where you're coming from but I've never run into that issue because I never quote commands or keywords, instead I change the typeface. Still, I'm a huge fan of altering grammar in small, consistent ways for the sake of clarity (that's where style guides come in).
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.
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.
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. :)
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.
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.
> 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.
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. ;)
Jerry Pournelle on writing:
http://www.jerrypournelle.com/slowchange/myjob.html
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.
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.
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.