

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

======
patio11
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
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.

~~~
weeksie
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
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.

~~~
weeksie
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).

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

------
greyman
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.

~~~
RyanMcGreal
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. :)

------
tel
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.

------
jokull
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.

------
RyanMcGreal
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
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
Jerry Pournelle on writing:

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

------
tptacek
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
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.

