Embed Doc
Copy Link
Readcast
Collections

CommentGo Back

Download

Documentation. It's one of the necessary evils of a softwareor hardware project. There are a couple schools of thoughtabout documentation. There are those who think it isn'tnecessary. Then there are people who need and usedocumentation. Among them, there are those who oftenhave a bad relationship with it.The frustrated user. Documentation is supposed to helpprevent that frustration. Far too often, documentation

causes

more frustration that it prevents or alleviates. That's becauseit doesn't get to the point. At least, not quickly enough forusers. Or it doesn't contain the information that users need inthe way that they need it.It doesn't have to be that way. During this presentation, I'mgoing to discuss a different way of looking at and creatingdocumentation. I'll be looking at ways of creating simple,powerful documentation. Documentation that puts the needsof the user

first

and

foremost

Another path: keep it simple

Simple. It's not a four letter word, but it's often treated likeone. Simple doesn't mean incomplete, inadequate, or

Keep It Simple: Streamline your documentation to make it moreeffective

By: Scott Nesbitt

dumbed down.To me, simple means minimal. It means

streamlined

. When creating documentation, we really needto start with this question:

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

That one question is a common thread in my thinking aboutdocumentation. In a lot of cases, the answer to that questionis no.Let's consider the purpose of documentation. It's supposedto take users from that stage of fumbling in the dark to alevel of mastery. Or, at the very least, put them on firmerfooting and start them down the road to mastery. The key togood documentation is

showing

users how to do things, andnot telling them what a piece of software or hardware can do.I mentioned streamlining documentation a moment ago.Effective streamlining makes and keeps documentationsimple. 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 blogabout minimalism in documentation. Someone responded ontheir blog with a post title

1.0 + 2.0 =1.5?

Obviously, thatperson didn't agree with me ...The main thrust of that person's argument was a) they likedhaving excess information in documentation, and b)documentation without that information isn't complete.This goes back to what I said earlier:

simple doesn't meanincomplete

. It means giving users the information that theyneed, in the way that they need it. If that means removingany material that disrupts the main flow of thedocumentation, so be it. More on this soon.

Why go minimal?

Documentation isn't a novel or a general non-fiction book. Itgenerally doesn't follow the beginning-middle-end structurethat stories are said to have. It's normal for a beginner'sguide to take the reader step-by-step through the basics. Butyou also have to remember that people often aren't justlearning from the documentation.They do a lot of jumping around. Think of language learningtextbooks. They generally follow a strict flow. When youmove between levels in a textbook series, the next one upgenerally starts where the other one left off. This structuredoesn't take into account what learners have picked up inother ways and from other sources. Documentation is thesame.You need to boil documentation down to its essentials.Remove any superfluous information. Show the user

how

todo things with an application or device; don't

tell

them what itcan do. You might wind up with documentation that's just a

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

Ditch the manual

Don't take those words literally. It's more advice on how toconstruct documentation.Remember what I said earlier about documentation not reallyhaving a beginning, a middle, and an end? Well, there are alarge number of technical writers who were English majors.And, traditionally, a lot of documentation has followed thatparticular narrative flow.You probably know what I'm talking about: a systematic walkthrough of the major features and functions of an applicationor a device – from starting it up to navigating the interface todoing various things.Often, a lot of background and overview information isincluded. To me, that's like the fat on a piece of beef. With allthat extra information, you wind up with something thateveryone hates: a thick manual.

Start cutting

A key idea behind streamlining documentation is getting ridof anything that doesn't advance the goal of the user. Andadvancing the goal is the user is the purpose of yourdocumentation. In order to do that, you need to cut awayanything that the user won't need.Ask yourself how important certain information in a manualis. Chances are that you'll realize much of that informationgets in the way of the main flow of the documentation. Theflow that is showing readers how to do things.If that's the case, then remove the extra information. Butdon'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 someplanning. Take a look at all of the content in yourdocumentation that explains

what

and not

how

. Then thinkabout:1.What you can keep in the documentation2.How to make that content unobtrusive in thedocumentation3.Where you can move that content if you don't want itin the main documentation4.How users will get to it from the main body of thedocumentationDoing 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 alreadyguessed: overview, background, and reference information.Any list of new features. Content like that.

of 00

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

The notes for a presentation given by Scott Nesbitt of DMN Communications at FSOSS 2009. The document looks at ways in which technical writers can streamline their documentation... (More)

Download or Print

504 Reads

Info and Rating

Category:	How-To Guides/Manuals
Rating:
Upload Date:	10/29/2009
Copyright:	Attribution Non-commercial
Tags:	writing documentation technical writing technical communication user assistance writing documentation technical writing technical communication user assistance (fewer)