Technical style
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.”