Writing great documentation:
Technical style
Jacob Kaplan-Moss
November 11, 2009
Part of the
Writing great documentation series.
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.
So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot.
Writing English isn’t any different than writing code: the more you do it, the better you get. You could take a class — most community colleges have pretty good beginning writing classes — but the important part really is to just write a lot. Over time, you’ll get better.
That’s how those of us with humanities degrees (I’ve got a degree in American Literature, also known as a “B.A. in B.S.”) become good writers: our degrees force us to write to the point that it comes easily. I think I wrote about ten to twenty pages a week each of my four years in college. That forced me to internalize grammar and form a personal style.
You’ll probably want to balance out all this writing with a healthy dose of reading, too. Learn to identify the mechanical parts of what makes a piece of writing effective; try to identify what succeeds (and what fails) about everything you read.
Watch for how authors accomplish “tone”. Read through a number of pieces by the same author; you should be able to identify what makes that person’s writing distinctive. Malcolm Gladwell would be one good choice here: his writing style is quite distinctive, somewhat formulaic, and he’s got dozens of his articles online. Most importantly, Gladwell’s style is one that’d work very well for technical documentation — he’s got a breezy, fun, conversational tone that nonetheless can communicate specific technical topics clearly.
It doesn’t matter all that much what you’re writing and reading. Sure, there are different rules for fiction and non-fiction, literary criticism and technical documentation, etc. The important aspects don’t change, though: good writing is clear, succinct, and communicates ideas effectively.
Most importantly: don’t let style stop you. In a moment I’m going to start covering the rules and suggestions of good grammar and style. It’s easy to get caught up in wanting your prose to be perfect from the first words you set down. It does’t work that way. While you’re writing, turn off the inner critic and just write. You can turn the critic back on when you proofread and edit later, but the important part is to just do it. Please don’t let anything else I’m about to say get in the way.
Grammar
Yes, you do need to use correct grammar. Grammar conventions exist to help us clearly communicate our thoughts without ambiguity or confusion. You need to understand the difference between “its” and “it’s;” between “there,” “they’re,” and “their;” and you need to understand why I’m putting the commas and semicolons in this sentence inside the quotes, not outside. (Since my audience is mostly programmers I shouldn’t have to spend extra time explaining why the consistent positioning of semicolons is so important!)
If you went to public school in the US you probably learned this stuff. If your public school was anything like mine, you probably forgot it all shortly after the final.
Again, a writing class could help if that’s how you like to learn. Me, I have a few of books that never leave my side:
Strunk and White’s The Elements of Style is probably the best-known grammar and style text. Its pithy, witty style makes it an actual pleasure to read — very unusual for grammar texts. It’s a bit long in the tooth these days (in fact, there’s recently been a bit of a backlash against some of the advice S&W gives), but if you take Strunk and White to heart you’ll be head and shoulders above the average writer.
(There’s also a really beautiful 50th anniversary edition if you want an edition that’s bound in a way befitting the work’s stature.)
Diana Hacker’s A Pocket Style Manual. This is a no-nonsense, quick-reference-style guide to grammar, punctuation, and mechanics. As a bonus, it has a quick-reference to the Chicago Manual, Modern Langauge Association (MLA), and American Psychological Association (APA) style guides.
I use it less frequently, but I also find the Handbook of Technical Writing useful. It’s a huge and comprehensive A-Z guide to language — there’s a section on “its” and “it’s,” one on the phrase “no doubt but,” and so on. (I’m sure there’s a section on “and so on.”) I’d recommend against diving into this one head-first; use it as a reference when you need to know the rules for using some particular phrase.
Style
Wait, back up. WTF are style guides?
While grammar rules are (fairly) set in stone, there’s any number of ways of formalizing style. Style guides tell you when to spell out numbers and when to write them as digits, where to use em- and en-dashes, how to cite sources, and all other manner of arcana.
The three that Hacker covers — Chicago Manual, MLA, and APA — are some of the most commonly used in academic publications. The Chicago Manual is popular in social science and historical settings; the MLA is used by most literary, media, and cultural publications; and the APA guide forms the basis of most scientific style guides. There are plenty of other style guides out there — large publications like the New York Times and the New Yorker have their own house style books — but unless you’re a total language geek they make pretty boring reading
The Django documentation mostly follows the Associated Press stylebook as a sort of homage to Django’s roots at a newspaper.
In the end, though, it really doesn’t make a whole lot of difference. The important lesson from all this is to be consistent. Readers find different stylistic choices off-putting, and they lend an uneven, unfinished tone to the documentation. Choose a stylebook, learn it, and then follow it… sometimes.
Good documentation style
Of course, careful breaking of the rules turns good writing into great writing. Most of the style rules you’ll find in these guides are oriented towards academic material, but I’m trying to help you write better documentation. There are important differences. Most style guides assume that writing will be presented in printed form, but most technical documentation is consumed online.
It’s well-known that people actually read differently on a computer screen; it’s probably also true that people read technical documentation differently from academic material.
Thus, the rest of this article will cover the areas that good documentation deviates from the standard “write well” advice in S&W, Hacker, and others.
Markup
There’s one huge difference between the way people read print and the way they read electrons: when people read online, they skim. Study after study has shown that readers skip a large percentage of the words that float by on their computer screens.
This means that good online documentation will feature a much heavier reliance on markup than most style guides allow for. In practice, this means:
Use inline markup liberally.
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 Nielsen, but whatever. Similarly, use markup for things like code samples,
entryversusoutput, and the like.This breaks up the monotony of large chunks of text and lets users skim between the different “important” parts of your document.
Write in short paragraphs.
If you compare good documentation to a typical magazine article or book chapter you’ll quickly notice a big difference in paragraph size. A book might have paragraphs that are ten, twenty, or dozens of sentences long, but it’s rare for good online documentation to even measure up to half that. The longest paragraphs in this document are about five or six sentences long.
Again, readers skim digital content. Breaking up your thoughts into smaller pieces facilitates this flow and ensures that important point don’t get missed because they’re buried in the middle of a wall of text.
Use a variety of structural elements.
Academic and journalistic writing don’t usually feature lists, tables, code blocks and the like. Most style guides omit advice on using them, or even prohibit their use. But they’re vital in technical documentation: tables and lists are particular important ways of presenting material.
Note
Callouts are especially useful; they can call attention to bits of content that might otherwise get lost, provide amusing or interesting digressions, or indicate that a particular bit of information is especially important.
Make your structure visual.
Your high school English teacher probably taught that section headers are “bad style” and that your whole paper should “flow” together. While flow’s important, it’s hard to accomplish in technical material. If you push it, you end up with pointless transitions — “now that we’ve talked about URLs, let’s talk about models!”
Headers are especially important to get right: they’ll stop skimmers as the fly by down the page. Headlines help reader quickly find the section of the document they’re looking for.
The above might seem obvious to those who’ve been writing for the web for some time. That’s the point; most technical documentation is consumed online, so most of this advice comes down to simply optimizing the content for the different task of reading online material. Print-designed material suffers when read online, so as you read about writing style always question whether the advice applies online.
Style
Online readers of technical material have different expectations of style. There’s a certain style that plays well to medium of online material and also helps facilitate the learning process that documentation is supposed to be facilitating.
Mostly, this style comes down to being approachable. Most style guides are oriented towards academic environments, and academic writing is notoriously stuffy. Expectations are different online, and what might be appropriate for a literary criticism journal just comes across as antiquated and obtuse online.
So I suggest:
Be conversational.
Write in a tone similar to how you talk. This doesn’t mean including all those verbal tics (“well…”, “you see”, “um…”), and it doesn’t mean throwing grammar rules out the window. If you use “gonna” in a technical document I’m “gonna” hate you.
But it does mean that contractions are okay, as is starting sentences with conjunctions.
Don’t be afraid to strike a personal tone.
You probably learned never to use “I” in a formal essay. Well, I’m here to tell you that it’s just fine in technical work. Showing your personal voice helps readers identify with the material, and that makes the material less intimidating.
You do need to be careful to be consistent with pronouns in collaborative works. You might choose to always use “I,” even in works written by different authors. Leonard Richardson and Sam Ruby took this path in RESTful Web services. Or you might choose to use “we”, even in parts written by a single author. Adrian and I went this way in the Django book. As long as you’re consistent, either approach works.
Do be careful with tenses and persons.
Most documentation, and especially tutorials, is written in the second person, future tense. That’s stuff like “first, you’ll need to install FooBar version 7. Then, when you’ve frozzled the whizbang, you can start working on the doodad.” This is the general form I prefer since documentation is essentially instructional material and I like the conceit that I’m personally instructing my readers.
Another common form is to couch everything in the first person plural: “first, we’ll need to install FooBar version 7…” This has advantages: it implies that the author is right there in the thick of things with the reader. But it can lead to confusion if later the author wants to be more conversational.
Once again there’s no “correct” way here, but you’ll want to think about this question, figure out a standard, and stick to it.
Watch out for passivity.
You’ve probably learned to avoid passive voice in your writing. That’s usually good advice, but it’s not the whole story; what I mean here is that good technical writing is active. The verb always appears first. Remember: you’re instructing people, so make it clear what to do at all times.
To illustrate, my first draft of the above paragraph started, “your high school English class probably taught you that passive voice was bad style.” That’s not passive voice (“… English class… taught…” is plenty active), but it does obscure the actual action in question — what “you… learned”. Starting the sentence with “you learned” brings the focus back onto you, the reader, hence keeping with the conversational, instructional tone I’m trying to strike.
Omit fluff.
This is best illustrated by example. Yesterday’s piece contained this ugly sentence:
This means that it should be pretty cross-sectional; a good tutorial should show off most of the different areas of the project.
A commenter (rightly) took me to task for this one: this sentence has a number of words (“pretty”, “most”, “good”) that don’t add any meaning to the sentence and some others (“different areas”, “the project”) that are vague.
Here’s a better version:
This means that it should be cross-sectional; a tutorial should show off the major areas of your project.
The meaning’s the same, but the second version is more forceful, clearer, and shorter. This is good.
Watch out for written tics.
Everyone’s got certain bad habits when it comes to writing. I think of these as written tics: little habits that have become nearly involuntary. Once you notice a writer’s tics it’s hard to stop noticing. The repetition just gets in the way.
For the record, my written tics are an over-reliance on semicolons and em-dashes; this document contains far too many — of each.
What’s next
All these rules can be incredibly overwhelming, I know. However, there’s a magical being that knows these rules and will remember them and apply them to your writing so that you don’t have to!
I’ll talk all about these magical creatures in tomorrow’s episode, titled: “You need an editor.”
Comments:
“Less frequently used, but also very helpful is my Handbook of Technical Writing.”
By the time I got to this entry in the list I'd forgotten that you where talking about the books on your self, such that this sentence appeared to be saying that the Handbook of Technical Writing is a book you wrote! Not what you intended, I think :-)
(Forgive this quibbling; criticising a style guide for stylistic gaffs is a rare pleasure in life and I could help but indulge :-)
Why ARE you putting the commas and semicolons inside the quotes? Did you have an actual reason in mind, other than "everyone does it that way?" Hey, did you notice how that quote is not a question, yet it ends in a question mark? What was that you said about ambiguity and confusion?
I propose that, on the contrary, we programmers should be in the forefront of repairing this bug in traditional usage. If the punctuation is part of the quotation, it goes inside the marks; otherwise, not. Especially in technical documentation, where punctuation is unusually significant.
I'm looking at "between ‘there,’ ‘they’re,’ and ‘there;’" and I have to say that the first and last "there"s look the same to me. Perhaps you meant "their" for one of them?
I'm also not convinced that I need to know why the semicolons go inside the quotes (because it makes the metal type last longer, according to Wikipedia: http://en.wikipedia.org/wik...), as long as I'm consistent about where I put the semicolons.
Jacob, putting punctuation marks inside quotes is a US convention (at least, it’s what the CMS advises). The international convention is to place the punctuation inside the quotes only if the punctuation is part of the quotation.
As a programmer I prefer this as it reduces ambiguity; the US style comes—if I ’m not mistaken—from a perception that it looks better when typeset, but personally I feel that the loss of clarity is worth it even that were true.
I disagree with your preference on punctuation in quotes, it made your punctuation (semicolons and commas) look like part of your examples rather than part of your sentences - it made me have to read the sentence multiple times to understand what was going on.
Then again, I'm British. Apparently we do our punctuation differently.
Going on to criticise myself: there really was no need for that last comment to be split over two paragraphs!
A thing I've found when writing tech docs is that keeping things to the singular helps too. Instead of composing a sentence like "Applications built with foobar may be frobnobbed using fleebars." it's usually clearer to say something like: "An application built using a foobar can be frobnbbed using a fleebar." I find that this helps me "keep it real", and I don't careen too quickly into useless abstraction.
I believe this site suffers from Skitt’s Law:
"That’s how of us with humanities degrees (I’ve got a degree in American Literature, also known as a “B.A. in B.S.”) become good writers: our degrees force us to write to the point that it comes easily."
It's rather ironic that a site suggesting good writing style itself has several simple grammatical errors :)
"We" is not third person! It's first person plural.
"But it does mean that contractions are okay, as is starting sentences with conjunctions."
Starting sentences with conjunctions is always okay. That this is ungrammatical, or bad style, is a myth.
http://languagelog.ldc.upen...
Thanks, nitpickers! I've fixed my typos and mistakes; I appreciate the editing.
I am with everyone else that the placement of punctuation should always depend on whether it’s part of the quotation or not. I will deviate a little in that I find it typographically tasteful if bottom punctuation written to the right of a quotation mark is pulled right-ward directly below the quotation mark in alignment with it, but that is purely a question of rendering (and often a hassle or impossible to realise). The “source” of the text should place the punctuation where it semantically belongs.
As for fluff, I disagree that the “good” in that sentence was. Here is how I would have edited it: “This means it should be cross-sectional. A good tutorial shows off the major areas of your project.” Here the second sentence is an assertion about what documentation is good, which explains the “should” in the previous sentence instead of merely redoubling it with no explanation. You make the point much more forcefully this way, and as a side benefit, you get to avoid an instance of your semicolon tic.
I was about to question everything I knew about punctuating quotes, since I put punctuation marks outside a quote. Thankfully, Peter's comment above includes a link clarifying that there are different conventions (incidentally, I'm Canadian).
To go off topic, from time to time I create sentences which end with a quote which in turn ends with an ellipsis - this results in a particularly ugly construction: "<sentence>...". I guess the best solution is just to avoid this whenever possible.
A small correction: it is "Jakob Nielsen", not "Neilsen" (assuming of course that we're both thinking of the Jakob that holds a Ph.D. in HCI and has an appearance similar to that of Tolkien's Gollum).
Thank you for another great post!
Cheers!
Jacob: Your comment system does not like the character 'ö' -- I've been trying to post a comment all day; it finally worked when i ditched my last name.
:)
"Yes, you do need to use correct grammar." => "Most of the style rules you’ll find in these guides is oriented towards academic material,..."
Still need some grammar cleanup. (Sorry, posts on grammar are held to a higher standard.) I had to look this one up to check on my internal grammar alarm. "Most of the water" would be singular, for example.
I'm enjoying the series. I agree completely with the broad guidelines, the need for consistency, inline markup, headings, and most everything else. +1, on the other hand, to the other commentators regarding punctuation.
I think the specifics about writing style are weaker. Good writing is hard to pin down, and I don't think that your admonishments about passivity and to "omit fluff" (cf. S&W's "omit needless words"?) are very helpful or will improve anybody's writing.
Finally, I've been convinced by the folks at languagelog that Strunk & White really is a silly text that out to be tossed. You might enjoy reading their critiques.
For a grammar guide that won't put you to sleep, I (and many others) recommend The Deluxe Transitive Vampire: A Handbook of Grammar for the Innocent, the Eager and the Doomed (http://bit.ly/8InM).
This fabulous book by Karen Elizabeth Gordon has all the same grammatical rules that these others do without the dry style.
This is snazzy :)
Thanks, Jacob!
"the fly by" --> "they fly by"
Under "Grammar" you say "clearly communicate". I am an old fart, but my eye is drawn to the split infinitive. What are your thoughts on that? Has everyone under forty already "boldly gone"?
PS. I am tempted to keep writing, because your font is quite lovely, with the ligature on the "fi" in "infinitive".
“Printed grammar since the 18th century created a fog based on the concept of correctness. Once this concept was pervasive, any hope of study of the actual dynamics of our language situation was obliterated. Our new media with their complex influence on language are similarly blanketed today.” (Marshall McLuhan, The effect of the printed book on language in the 16th century, 1957)
Thank you for perpetuating the fog.
Overusage of em-dash is one of my worse habits too. I think, at least in my case, it is a by-product of trying to use a conversational style—we use pauses to inhale and provide punctuation to the verbal flow.
I have no idea if this theory has any basis in science but it is handy to have a scapegoat.
I think that typography and design are the clothes in which you dress your words; the only thing I found missing from this brilliant post is a brief mention on how to make the text you write legible via sane typography best-practices, like
giving your text room to breathe by not having superwide text columns set solid (single-spaced).
Noteworthy resources include Bringhurst's "elements of Typographic Style" and its web cousin at webtypography.net. Apologies for lack of hyperlink, am writing from the iPhone.
Of course, looking over my comment the following morning, I lead off with broken pluralization and go downhill from there.
A school teacher friend of mine lent me "On Writing Well" and it was a great help. "The Elements of Style" is also a great start.
http://www.amazon.com/Writi...
Typo: "Modern Langauge Association".
Thanks for the practical advise! I've thoroughly enjoyed your instructional series on writing good documenation.
Beside the Style Guides you already mentioned which offer great information on how to write technical information, I also suggest the book "Developing Quality Technical Information", Second Edition - Gretchen Hargis, Michelle Carey, Ann Kilty Hernandez and others... It is a Handbook for writers and editors. I will give no further details insight this book...it's a please to read it. I found it very useful.
Enjoy it!
Leave a comment: