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 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 1

Keep It Simple: Streamline your documentation to make it more effective

By: Scott Nesbitt

dumbed down. To me, simple means minimal. It means streamlined. When creating documentation, we really need to start with this question:

Are we giving readers the information they want, in the way they want and need it?

That one question is a common thread in my thinking about documentation. In a lot of cases, the answer to that question is no.

Let's consider the purpose of documentation. It's supposed 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 footing and start them down the road to mastery. The key to good documentation is showing users how to do things, and not telling them what a piece of software or hardware can do.

I mentioned streamlining documentation a moment ago. Effective streamlining makes and keeps documentation simple. Streamlining has two branches:

● Changing the way documentation is structured

● Tightening up the writing

Going minimal

About a year ago, I wrote a long post on my company's blog about minimalism in documentation. Someone responded on their blog with a post title 1.0 + 2.0 =1.5? Obviously, that person didn't agree with me ...

The main thrust of that person's argument was a) they liked having excess information in documentation, and b) documentation without that information isn't complete.

This goes back to what I said earlier: simple doesn't mean incomplete. It means giving users the information that they need, in the way that they need it. If that means removing any material that disrupts the main flow of the documentation, so be it. More on this soon.

Why go minimal?

Documentation isn't a novel or a general non-fiction book. It generally doesn't follow the beginning-middle-end structure that stories are said to have. It's normal for a beginner's guide to take the reader step-by-step through the basics. But you also have to remember that people often aren't just learning from the documentation.

They do a lot of jumping around. Think of language learning textbooks. They generally follow a strict flow. When you move between levels in a textbook series, the next one up generally starts where the other one left off. This structure doesn't take into account what learners have picked up in other ways and from other sources. Documentation is the same.

You need to boil documentation down to its essentials. Remove any superfluous information. Show the user how to do things with an application or device; don't tell them what it can do. You might wind up with documentation that's just a

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 2

set of procedures connected by some linking material and cross references. And there's nothing wrong with that.

Ditch the manual

Don't take those words literally. It's more advice on how to construct documentation.

Remember what I said earlier about documentation not really having a beginning, a middle, and an end? Well, there are a large number of technical writers who were English majors. And, traditionally, a lot of documentation has followed that particular narrative flow.

You probably know what I'm talking about: a systematic walk through of the major features and functions of an application or a device – from starting it up to navigating the interface to doing various things.

Often, a lot of background and overview information is included. To me, that's like the fat on a piece of beef. With all that extra information, you wind up with something that everyone hates: a thick manual.

Start cutting

A key idea behind streamlining documentation is getting rid of anything that doesn't advance the goal of the user. And advancing the goal is the user is the purpose of your documentation. In order to do that, you need to cut away anything that the user won't need.

Ask yourself how important certain information in a manual is. Chances are that you'll realize much of that information gets in the way of the main flow of the documentation. The flow that is showing readers how to do things.

If that's the case, then remove the extra information. But don't send it spinning to the equivalent of /dev/null. Instead, shunt it somewhere else. More on this in a few moments.

Before you get the scalpel (or chainsaw) out, do some planning. Take a look at all of the content in your documentation that explains what and not how. Then think about:

1. What you can keep in the documentation

2. How to make that content unobtrusive in the documentation

3. Where you can move that content if you don't want it in the main documentation

4. How users will get to it from the main body of the documentation

Doing all of that will take some time. But those are worthwhile steps.

What's up front

So, what's the first thing to go? You might have already guessed: overview, background, and reference information. Any list of new features. Content like that.

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 3

Over the years, I've found that people using an application or a gadget don't really want or need that information. Well, maybe at first. That kind of information helps user get the lay of the land, but it's not essential.

Overall, though, that overview, background, and reference information definitely gets in the way of users getting things done. And that information isn't going to do much to help users gain the level of proficiency or mastery that they seek.

Remember, though, that just because the information isn't in the face of the user doesn't mean that it doesn't exist. It can be somewhere else, a click or two away. More on where this somewhere else can be in a moment.

Images

A picture is worth a thousand words, or so the saying goes. But when your focus shifts to screen captures, are those thousand words worth saying? Or are screen captures just unnecessary filler?

I've found that often it's the latter. There are quite a few technical writers who create documentation that’s packed with screen captures, diagrams, flowcharts, and other images. In most cases, the images don’t do much for the document except take up space.

Images included in documentation need to be more than just mere eye candy. The should illustrate something that’s difficult to describe using words alone. Images enhance the text; they don’t replace it. To be honest, most images that

I’ve seen in many of the user guides that I’ve read have done nothing to enhance the text I was reading. They just mirrored what I was reading. Digital repetition at its finest.

I’ve heard some technical communicators argue that including screen captures is important because they let the user see what’s happening in the application. What we fail to realize is that someone will be probably be using the documentation while in front of an application or gadget. Unless they’re trying to familiarize themselves with a product, they won’t read the docs while riding the bus home or just after eating dinner.

That said, images aren’t always unwelcome. A well-chosen image is useful. But the key words here are well and chosen. Just capturing every screen you can and sandwiching it between blocks of text doesn’t work. Like anything else in your document, images should have a purpose. If they don’t have a purpose, strip them out.

Think outside the ToC

Look at the table of content of the typical manual or online help file. It's a tree-like structure. The table of contents follows a familiar narrative flow – beginning, middle, and end. But who reads documentation from cover to cover?

Hypertext has changed the way in which people access information. In fact, I think that hypertext follows the thought and usage patterns of most user better than the tree-like table of contents. There's a lot of jumping around, rather than taking a straight line through the documentation.

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 4

Remember, we're not telling a story with documentation. We're using documentation to show users how to get things done.

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 a bit too linear and restrictive. The way I prefer to organize documentation is to group similar tasks – for example, all topics that cover importing and exporting data. One way to structure the hierarchy of topics is to lead off with a question like How do I ...? Or, you can have a heading like Importing and Exporting, followed by a list of topics – for example, How to Export Your Data to CSV.

Think in terms of topics

Topic-based writing is all the rage in technical communication circles right now. Topic-based writing is essentially a way of moving from looking at a manual as a whole and instead thinking about it in terms of the components of that manual.

Those components are topics. A topic is a standalone piece of content. It doesn’t rely on any other piece of content in a manual or help system. The example I gave earlier, how to export data to CSV, would be considered a topic.

Taking this approach enables you to write a lot of documentation quickly. You can also stitch the topics together and by doing so create customized documentation. The drawback to this technique is that when topics are stitched together there's often no continuity between

sections and topics. It can make for a disjointed read, assuming someone is reading the manual from cover to cover.

Where to put the cut content

It all depends on the infrastructure that a project has. Two locations that I prefer are a wiki and a knowledge base.

Whether or not a wiki is your means of delivering documentation, a wiki is a good home for all of the extraneous information that you've cut out of the 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 is set up a namespace on the wiki. A namespace is like a directory on your computer. It's used to group a set of wiki pages that contain related content.

A knowledge base is also a good choice. At my last salaried job, I cut a lot of content out of the manual that I took over. Quite a bit of that content was useful, but it just didn't fit into the flow of the manual. Instead of tossing it into digital oblivion, I re-purposed that information as a set of articles for the company's customer knowledge base. I had to do some rewriting to make it a little more palatable for the Web. And I linked extensively between the documentation and the knowledge base.

Don't have a dedicated knowledge base? That's not a problem. You can use a wiki. And if your user base contributes to the documentation, a wiki is a good space for

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 5

that too. That's another presentation for another time.

Writing

As I mentioned earlier, writing is the second component of streamlining. In some ways, it's the most important. Remember, it's called technical writing for a reason ...

I'm not trying to say that FLOSS technical writers can't write. Quite the opposite is true. There are a number of exceptional technical writers in the ranks of the people creating documentation for FLOSS. I've been doing this job for almost 15 years, and I've learned a few things about crafting user manuals from reading FLOSS documentation.

That said, there's always room to improve. I'd like to offer some advice on streamlining your writing.

Listen to the radio

When writing documentation, my ideal model is a good radio report. Sounds kind of strange, doesn't it? If you think about it for a moment, though, a radio report has all the elements of a good piece of documentation:

● It's short and to the point

● Where necessary, it contains just enough background to orient the listener

● It contains all the important facts, compressed into small space in time

Good task-based documentation does the same thing.

Write as you'd speak

Many of us have been taught that we need to write in a more formal tone. Admittedly, there’s not a whole lot wrong with that. Technical writing doesn’t have to be scintillating prose a la … well, fill in the name of your favourite novelist here (I’m partial to James Salter myself). But documentation doesn’t have to be dry and boring like an academic tract or the articles that are published in a certain periodicals.

This is where I think the FLOSS world has an advantage over corporate technical communication. In many cases, FLOSS documentation is written in a more informal, relaxed style. It doesn't sound like the often stiff, bland, homogenized business-like prose you find in corporate documentation.

Why do we wind up with dull writing in documentation? Sometimes, technical writers get complacent or caught up in a set of writing standards. When that happens,the usability of the documentation suffers.

You’ve probably heard people talking about documentation as a conversation. Why not interpret that literally and write as you’d speak? Clarity can come from writing in a more natural, conversational way.

You might have to break a few rules of grammar. That shouldn’t matter if your writing is clear and gets the point across succinctly. Technical writer and blogger Tom Johnson shared a few interesting thoughts about this. The key point in

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 6

Tom's post was:

[T]he user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses.

Of course, you want to eliminate all of the the umms, ahhs, and y’knows. Eliminate the pop culture references, clever turns of phrase, and jokey allusions that you might normally use when speaking to friends, family, or colleagues.

Write tightly

My background is journalism. When I was in journalism school, the instructors constantly pressured me and my classmates to write tightly. All that means is removing excess words or rewriting a sentence or a paragraph so that it's shorter, but still makes sense.

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 limit sentences to 20 words. Preferably less. You don’t need to view that as a hard and fast rule, though.

Words, words, words

Wordiness permeates a lot of documentation. A lot of that wordiness is caused by loose and redundant writing. Two of the worst offenders, and the two that I dislike the most, are That is and In other words.

What do I mean? You'll have a sentence that explains something. The sentence following it will start of with That is and In other words and will reiterate the preceding sentence. What's the point of that? It says to me that the writer wasn't doing his or her job properly, or that he or she is being paid by the word.

Here's an example from some documentation that I streamlined:

You can search your folders for all media of a specific type. That is, you can search folders for all images, audio files, video clips, or documents.

I can understand why things are done like this: the second sentence clarifies the first one. But if done properly, it's not needed. Let's go back to the example I just mentioned. I rewrote it as:

You can search your folders for images, audio files, video clips, or documents.

That rewrite trimmed the passage in half, and still kept its meaning. If you've written something like that or run into it, consider combining the two sentences. Or, deleting the one that starts with That is or In other words.

Sometimes more is better

While I'm a stickler for writing tightly, there are situations in which you need to use a few more words. Let's look at this example:

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 7

... based on application status

It's short. But it sounds too much like developer speak, and it really doesn't sound natural. So, how about this instead:

... based on the status of the application

It's slightly longer, but it's not as clipped and makes a bit more sense. If you need to write longer sentences to achieve clarity, by all means do so.

Summing up

Documentation should be about showing users how to do 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:

● Clear

● Concise

● Consistent

● Complete

● Correct

Then you're doing your readers a disservice.

Documentation should be simple and designed for the needs of the user. The process isn't painless, but the goal of that process is within your reach. And it's definitely a worthwhile goal.

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 8

Contact MeWeb site:

http://scottnesbitt.net

Email:

scott@scottnesbitt.net

Blog:

http://weblog.scottnesbitt.net

Twitter:

http://www.twitter.com/ScottWNesbitt

© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 9