Keep It Simple: Streamline your documentation to make it more
effective
By: Scott Nesbitt
Documentation. It's one of the necessary evils of a software
or hardware project. There are a couple schools of thought
about documentation. There are those who think it isn't
necessary. Then there are people who need and use
documentation. Among them, there are those who often
have a bad relationship with it.
The frustrated user. Documentation is supposed to help
prevent that frustration. Far too often, documentation causes
more frustration that it prevents or alleviates. That's because
it doesn't get to the point. At least, not quickly enough for
users. Or it doesn't contain the information that users need in
the way that they need it.
It doesn't have to be that way. During this presentation, I'm
going to discuss a different way of looking at and creating
documentation. I'll be looking at ways of creating simple,
powerful documentation. Documentation that puts the needs
of the user first and foremost.
Another path: keep it simple
Simple. It's not a four letter word, but it's often treated like
one. Simple doesn't mean incomplete, inadequate, or
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 1

dumbed down. To me, simple means minimal. It means The main thrust of that person's argument was a) they liked
streamlined. When creating documentation, we really need having excess information in documentation, and b)
to start with this question: documentation without that information isn't complete.
Are we giving readers the information they want, in the This goes back to what I said earlier: simple doesn't mean
way they want and need it? incomplete. It means giving users the information that they
need, in the way that they need it. If that means removing
That one question is a common thread in my thinking about any material that disrupts the main flow of the
documentation. In a lot of cases, the answer to that question documentation, so be it. More on this soon.
is no.
Let's consider the purpose of documentation. It's supposed Why go minimal?
to take users from that stage of fumbling in the dark to a
level of mastery. Or, at the very least, put them on firmer Documentation isn't a novel or a general non-fiction book. It
footing and start them down the road to mastery. The key to generally doesn't follow the beginning-middle-end structure
good documentation is showing users how to do things, and that stories are said to have. It's normal for a beginner's
not telling them what a piece of software or hardware can do. guide to take the reader step-by-step through the basics. But
I mentioned streamlining documentation a moment ago. you also have to remember that people often aren't just
Effective streamlining makes and keeps documentation learning from the documentation.
simple. Streamlining has two branches: They do a lot of jumping around. Think of language learning
● Changing the way documentation is structured textbooks. They generally follow a strict flow. When you
move between levels in a textbook series, the next one up
● Tightening up the writing generally starts where the other one left off. This structure
doesn't take into account what learners have picked up in
Going minimal other ways and from other sources. Documentation is the
same.
About a year ago, I wrote a long post on my company's blog You need to boil documentation down to its essentials.
about minimalism in documentation. Someone responded on Remove any superfluous information. Show the user how to
their blog with a post title 1.0 + 2.0 =1.5? Obviously, that do things with an application or device; don't tell them what it
person didn't agree with me ... can do. You might wind up with documentation that's just a
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 2

set of procedures connected by some linking material and Ask yourself how important certain information in a manual
cross references. And there's nothing wrong with that. is. Chances are that you'll realize much of that information
gets in the way of the main flow of the documentation. The
Ditch the manual flow that is showing readers how to do things.
If that's the case, then remove the extra information. But
Don't take those words literally. It's more advice on how to don't send it spinning to the equivalent of /dev/null. Instead,
construct documentation. shunt it somewhere else. More on this in a few moments.
Remember what I said earlier about documentation not really Before you get the scalpel (or chainsaw) out, do some
having a beginning, a middle, and an end? Well, there are a planning. Take a look at all of the content in your
large number of technical writers who were English majors. documentation that explains what and not how. Then think
And, traditionally, a lot of documentation has followed that about:
particular narrative flow. 1. What you can keep in the documentation
You probably know what I'm talking about: a systematic walk 2. How to make that content unobtrusive in the
through of the major features and functions of an application documentation
or a device – from starting it up to navigating the interface to
doing various things. 3. Where you can move that content if you don't want it
in the main documentation
Often, a lot of background and overview information is
included. To me, that's like the fat on a piece of beef. With all 4. How users will get to it from the main body of the
that extra information, you wind up with something that documentation
everyone hates: a thick manual. Doing all of that will take some time. But those are
worthwhile steps.
Start cutting
A key idea behind streamlining documentation is getting rid What's up front
of anything that doesn't advance the goal of the user. And So, what's the first thing to go? You might have already
advancing the goal is the user is the purpose of your guessed: overview, background, and reference information.
documentation. In order to do that, you need to cut away Any list of new features. Content like that.
anything that the user won't need.
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 3

Over the years, I've found that people using an application or I’ve seen in many of the user guides that I’ve read have done
a gadget don't really want or need that information. Well, nothing to enhance the text I was reading. They just mirrored
maybe at first. That kind of information helps user get the what I was reading. Digital repetition at its finest.
lay of the land, but it's not essential.
I’ve heard some technical communicators argue that
Overall, though, that overview, background, and reference including screen captures is important because they let the
information definitely gets in the way of users getting things user see what’s happening in the application. What we fail to
done. And that information isn't going to do much to help realize is that someone will be probably be using the
users gain the level of proficiency or mastery that they seek. documentation while in front of an application or gadget.
Unless they’re trying to familiarize themselves with a
Remember, though, that just because the information isn't in
product, they won’t read the docs while riding the bus home
the face of the user doesn't mean that it doesn't exist. It can
or just after eating dinner.
be somewhere else, a click or two away. More on where this
somewhere else can be in a moment. That said, images aren’t always unwelcome. A well-chosen
image is useful. But the key words here are well and chosen.
Images Just capturing every screen you can and sandwiching it
between blocks of text doesn’t work. Like anything else in
A picture is worth a thousand words, or so the saying goes. your document, images should have a purpose. If they don’t
But when your focus shifts to screen captures, are those have a purpose, strip them out.
thousand words worth saying? Or are screen captures just
unnecessary filler?
Think outside the ToC
I've found that often it's the latter. There are quite a few
Look at the table of content of the typical manual or online
technical writers who create documentation that’s packed
help file. It's a tree-like structure. The table of contents
with screen captures, diagrams, flowcharts, and other
follows a familiar narrative flow – beginning, middle, and end.
images. In most cases, the images don’t do much for the
But who reads documentation from cover to cover?
document except take up space.
Hypertext has changed the way in which people access
Images included in documentation need to be more than just
information. In fact, I think that hypertext follows the thought
mere eye candy. The should illustrate something that’s
and usage patterns of most user better than the tree-like
difficult to describe using words alone. Images enhance the
table of contents. There's a lot of jumping around, rather
text; they don’t replace it. To be honest, most images that
than taking a straight line through the documentation.
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 4

Remember, we're not telling a story with documentation. sections and topics. It can make for a disjointed read,
We're using documentation to show users how to get things assuming someone is reading the manual from cover to
done. cover.
I don't think that the table of contents is the best way to
organize documentation. It's familiar, but as I said before it's Where to put the cut content
a bit too linear and restrictive. The way I prefer to organize It all depends on the infrastructure that a project has. Two
documentation is to group similar tasks – for example, all locations that I prefer are a wiki and a knowledge base.
topics that cover importing and exporting data. One way to
structure the hierarchy of topics is to lead off with a question Whether or not a wiki is your means of delivering
like How do I ...? Or, you can have a heading like Importing documentation, a wiki is a good home for all of the
and Exporting, followed by a list of topics – for example, How extraneous information that you've cut out of the
to Export Your Data to CSV. documentation – overview, background, and reference
material. Most FLOSS projects use a wiki for various
purposes, so why not piggy back on that? All you need to do
Think in terms of topics
is set up a namespace on the wiki. A namespace is like a
Topic-based writing is all the rage in technical directory on your computer. It's used to group a set of wiki
communication circles right now. Topic-based writing is pages that contain related content.
essentially a way of moving from looking at a manual as a
A knowledge base is also a good choice. At my last salaried
whole and instead thinking about it in terms of the
job, I cut a lot of content out of the manual that I took over.
components of that manual.
Quite a bit of that content was useful, but it just didn't fit into
Those components are topics. A topic is a standalone piece the flow of the manual. Instead of tossing it into digital
of content. It doesn’t rely on any other piece of content in a oblivion, I re-purposed that information as a set of articles for
manual or help system. The example I gave earlier, how to the company's customer knowledge base. I had to do some
export data to CSV, would be considered a topic. rewriting to make it a little more palatable for the Web. And I
linked extensively between the documentation and the
Taking this approach enables you to write a lot of
knowledge base.
documentation quickly. You can also stitch the topics
together and by doing so create customized documentation. Don't have a dedicated knowledge base? That's not a
The drawback to this technique is that when topics are problem. You can use a wiki. And if your user base
stitched together there's often no continuity between contributes to the documentation, a wiki is a good space for
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 5

that too. That's another presentation for another time. Good task-based documentation does the same thing.
Writing Write as you'd speak
Many of us have been taught that we need to write in a more
As I mentioned earlier, writing is the second component of formal tone. Admittedly, there’s not a whole lot wrong with
streamlining. In some ways, it's the most important. that. Technical writing doesn’t have to be scintillating prose a
Remember, it's called technical writing for a reason ... la … well, fill in the name of your favourite novelist here (I’m
partial to James Salter myself). But documentation doesn’t
I'm not trying to say that FLOSS technical writers can't write.
have to be dry and boring like an academic tract or the
Quite the opposite is true. There are a number of exceptional
articles that are published in a certain periodicals.
technical writers in the ranks of the people creating
documentation for FLOSS. I've been doing this job for almost This is where I think the FLOSS world has an advantage
15 years, and I've learned a few things about crafting user over corporate technical communication. In many cases,
manuals from reading FLOSS documentation. FLOSS documentation is written in a more informal, relaxed
style. It doesn't sound like the often stiff, bland, homogenized
That said, there's always room to improve. I'd like to offer
business-like prose you find in corporate documentation.
some advice on streamlining your writing.
Why do we wind up with dull writing in documentation?
Listen to the radio Sometimes, technical writers get complacent or caught up in
a set of writing standards. When that happens,the usability of
When writing documentation, my ideal model is a good radio
the documentation suffers.
report. Sounds kind of strange, doesn't it? If you think about
it for a moment, though, a radio report has all the elements You’ve probably heard people talking about documentation
of a good piece of documentation: as a conversation. Why not interpret that literally and write as
you’d speak? Clarity can come from writing in a more
● It's short and to the point
natural, conversational way.
● Where necessary, it contains just enough background You might have to break a few rules of grammar. That
to orient the listener shouldn’t matter if your writing is clear and gets the point
● It contains all the important facts, compressed into across succinctly. Technical writer and blogger Tom Johnson
small space in time shared a few interesting thoughts about this. The key point in
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 6

Tom's post was: What do I mean? You'll have a sentence that explains
something. The sentence following it will start of with That is
[T]he user just wants a brief, clear explanation of a
and In other words and will reiterate the preceding sentence.
concept or task. The user will glance and skim —
What's the point of that? It says to me that the writer wasn't
reading behaviors hardly worthy of the elitist
doing his or her job properly, or that he or she is being paid
grammarian who argues the finer points of “which”
by the word.
versus “that” in restrictive clauses.
Here's an example from some documentation that I
Of course, you want to eliminate all of the the umms, ahhs, streamlined:
and y’knows. Eliminate the pop culture references, clever
turns of phrase, and jokey allusions that you might normally You can search your folders for all media of a specific
use when speaking to friends, family, or colleagues. type. That is, you can search folders for all images,
audio files, video clips, or documents.
Write tightly I can understand why things are done like this: the second
My background is journalism. When I was in journalism sentence clarifies the first one. But if done properly, it's not
school, the instructors constantly pressured me and my needed. Let's go back to the example I just mentioned. I
classmates to write tightly. All that means is removing rewrote it as:
excess words or rewriting a sentence or a paragraph so that You can search your folders for images, audio files,
it's shorter, but still makes sense. video clips, or documents.
Assume that you’re writing for the Web, even if you’re not.
One piece of advice that’s given to aspiring Web writers is to That rewrite trimmed the passage in half, and still kept its
limit sentences to 20 words. Preferably less. You don’t need meaning. If you've written something like that or run into it,
to view that as a hard and fast rule, though. consider combining the two sentences. Or, deleting the one
that starts with That is or In other words.
Words, words, words
Sometimes more is better
Wordiness permeates a lot of documentation. A lot of that
wordiness is caused by loose and redundant writing. Two of While I'm a stickler for writing tightly, there are situations in
the worst offenders, and the two that I dislike the most, are which you need to use a few more words. Let's look at this
That is and In other words. example:
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 7

... based on application status ● Clear
It's short. But it sounds too much like developer speak, and it ● Concise
really doesn't sound natural. So, how about this instead: ● Consistent
... based on the status of the application ● Complete
It's slightly longer, but it's not as clipped and makes a bit ● Correct
more sense. If you need to write longer sentences to achieve
clarity, by all means do so. Then you're doing your readers a disservice.
Documentation should be simple and designed for the needs
Summing up of the user. The process isn't painless, but the goal of that
process is within your reach. And it's definitely a worthwhile
Documentation should be about showing users how to do goal.
things. It should help take them from fumbling in the dark,
put them on firmer footing and start them down the road to
mastery. Technology book publisher Tim O'Reilly said it best:
People are looking for advanced tips and tricks.
They're not looking for the basics. They're looking for
things that will give them more of an edge.
Don’t bog users down with what’s not necessary for them to
get things done in a fast and efficient way. With today's
technology, no information goes missing. You just need to
link to anything that isn't in the main flow of your
documentation.
It's the quality of the content and how it's organized that
makes your documentation successful. If it doesn't follow
what I call the 5 Cs:
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 8

Contact Us
Web site:
http://www.dmncommunications.com
Email:
info@dmncommunications.com
Blog:
http://www.dmncommunications/com/weblog
Twitter:
http://www.twitter.com/dmnguys
Podcast:
http://dmn.podbean.com
© 2009 DMN Communications Keep It Simple: Streamline your documentation to make it more effective - 9