Keep It Simple - Notes


Published on

Notes for a presentation that I gave at FSOSS 2009 on keeping documentation simple and direct to make it more effective.

Published in: Technology, Business
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Keep It Simple - Notes

  1. 1. Keep It Simple: Streamline your documentation to make it moreeffectiveBy: Scott Nesbitt Documentation. Its 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 isnt 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. Thats because it doesnt get to the point. At least, not quickly enough for users. Or it doesnt contain the information that users need in the way that they need it. It doesnt have to be that way. During this presentation, Im going to discuss a different way of looking at and creating documentation. Ill 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. Its not a four letter word, but its often treated like one. Simple doesnt mean incomplete, inadequate, or© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 1
  2. 2. dumbed down. To me, simple means minimal. It means The main thrust of that persons argument was a) they likedstreamlined. When creating documentation, we really need having excess information in documentation, and b)to start with this question: documentation without that information isnt complete. Are we giving readers the information they want, in the This goes back to what I said earlier: simple doesnt 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 removingThat one question is a common thread in my thinking about any material that disrupts the main flow of thedocumentation. In a lot of cases, the answer to that question documentation, so be it. More on this no.Lets consider the purpose of documentation. Its supposed Why go minimal?to take users from that stage of fumbling in the dark to alevel of mastery. Or, at the very least, put them on firmer Documentation isnt a novel or a general non-fiction book. Itfooting and start them down the road to mastery. The key to generally doesnt follow the beginning-middle-end structuregood documentation is showing users how to do things, and that stories are said to have. Its normal for a beginnersnot telling them what a piece of software or hardware can do. guide to take the reader step-by-step through the basics. ButI mentioned streamlining documentation a moment ago. you also have to remember that people often arent justEffective 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 doesnt take into account what learners have picked up inGoing minimal other ways and from other sources. Documentation is the same.About a year ago, I wrote a long post on my companys 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 totheir blog with a post title 1.0 + 2.0 =1.5? Obviously, that do things with an application or device; dont tell them what itperson didnt agree with me ... can do. You might wind up with documentation thats just a© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 2
  3. 3. set of procedures connected by some linking material and Ask yourself how important certain information in a manualcross references. And theres nothing wrong with that. is. Chances are that youll realize much of that information gets in the way of the main flow of the documentation. TheDitch the manual flow that is showing readers how to do things. If thats the case, then remove the extra information. ButDont take those words literally. Its more advice on how to dont 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 somehaving a beginning, a middle, and an end? Well, there are a planning. Take a look at all of the content in yourlarge number of technical writers who were English majors. documentation that explains what and not how. Then thinkAnd, traditionally, a lot of documentation has followed that about:particular narrative flow. 1. What you can keep in the documentationYou probably know what Im talking about: a systematic walk 2. How to make that content unobtrusive in thethrough of the major features and functions of an application documentationor a device – from starting it up to navigating the interface todoing various things. 3. Where you can move that content if you dont want it in the main documentationOften, a lot of background and overview information isincluded. To me, thats like the fat on a piece of beef. With all 4. How users will get to it from the main body of thethat extra information, you wind up with something that documentationeveryone hates: a thick manual. Doing all of that will take some time. But those are worthwhile steps.Start cuttingA key idea behind streamlining documentation is getting rid Whats up frontof anything that doesnt advance the goal of the user. And So, whats the first thing to go? You might have alreadyadvancing 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 wont need.© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 3
  4. 4. Over the years, Ive found that people using an application or I’ve seen in many of the user guides that I’ve read have donea gadget dont really want or need that information. Well, nothing to enhance the text I was reading. They just mirroredmaybe at first. That kind of information helps user get the what I was reading. Digital repetition at its finest.lay of the land, but its not essential. I’ve heard some technical communicators argue thatOverall, though, that overview, background, and reference including screen captures is important because they let theinformation definitely gets in the way of users getting things user see what’s happening in the application. What we fail todone. And that information isnt going to do much to help realize is that someone will be probably be using theusers 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 aRemember, though, that just because the information isnt in product, they won’t read the docs while riding the bus homethe face of the user doesnt mean that it doesnt exist. It can or just after eating somewhere else, a click or two away. More on where thissomewhere 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 inA picture is worth a thousand words, or so the saying goes. your document, images should have a purpose. If they don’tBut when your focus shifts to screen captures, are those have a purpose, strip them out.thousand words worth saying? Or are screen captures justunnecessary filler? Think outside the ToCIve found that often its the latter. There are quite a few Look at the table of content of the typical manual or onlinetechnical writers who create documentation that’s packed help file. Its a tree-like structure. The table of contentswith 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 accessImages included in documentation need to be more than just information. In fact, I think that hypertext follows the thoughtmere eye candy. The should illustrate something that’s and usage patterns of most user better than the tree-likedifficult to describe using words alone. Images enhance the table of contents. Theres a lot of jumping around, rathertext; they don’t replace it. To be honest, most images that than taking a straight line through the documentation.© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 4
  5. 5. Remember, were not telling a story with documentation. sections and topics. It can make for a disjointed read,Were using documentation to show users how to get things assuming someone is reading the manual from cover todone. cover.I dont think that the table of contents is the best way toorganize documentation. Its familiar, but as I said before its Where to put the cut contenta bit too linear and restrictive. The way I prefer to organize It all depends on the infrastructure that a project has. Twodocumentation 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 tostructure the hierarchy of topics is to lead off with a question Whether or not a wiki is your means of deliveringlike How do I ...? Or, you can have a heading like Importing documentation, a wiki is a good home for all of theand Exporting, followed by a list of topics – for example, How extraneous information that youve cut out of theto 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 doThink in terms of topics is set up a namespace on the wiki. A namespace is like aTopic-based writing is all the rage in technical directory on your computer. Its used to group a set of wikicommunication 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 salariedwhole 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 didnt fit intoThose components are topics. A topic is a standalone piece the flow of the manual. Instead of tossing it into digitalof content. It doesn’t rely on any other piece of content in a oblivion, I re-purposed that information as a set of articles formanual or help system. The example I gave earlier, how to the companys customer knowledge base. I had to do someexport 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 theTaking this approach enables you to write a lot of knowledge base.documentation quickly. You can also stitch the topicstogether and by doing so create customized documentation. Dont have a dedicated knowledge base? Thats not aThe drawback to this technique is that when topics are problem. You can use a wiki. And if your user basestitched together theres often no continuity between 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
  6. 6. that too. Thats another presentation for another time. Good task-based documentation does the same thing.Writing Write as youd speak Many of us have been taught that we need to write in a moreAs I mentioned earlier, writing is the second component of formal tone. Admittedly, there’s not a whole lot wrong withstreamlining. In some ways, its the most important. that. Technical writing doesn’t have to be scintillating prose aRemember, its 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’tIm not trying to say that FLOSS technical writers cant write. have to be dry and boring like an academic tract or theQuite 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 creatingdocumentation for FLOSS. Ive been doing this job for almost This is where I think the FLOSS world has an advantage15 years, and Ive 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 doesnt sound like the often stiff, bland, homogenizedThat said, theres always room to improve. Id 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 ofWhen writing documentation, my ideal model is a good radio the documentation Sounds kind of strange, doesnt it? If you think aboutit for a moment, though, a radio report has all the elements You’ve probably heard people talking about documentationof 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 ● Its 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 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 6
  7. 7. Toms post was: What do I mean? Youll 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 — Whats the point of that? It says to me that the writer wasnt 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. Heres an example from some documentation that IOf course, you want to eliminate all of the the umms, ahhs, streamlined:and y’knows. Eliminate the pop culture references, cleverturns of phrase, and jokey allusions that you might normally You can search your folders for all media of a specificuse 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 secondMy background is journalism. When I was in journalism sentence clarifies the first one. But if done properly, its notschool, the instructors constantly pressured me and my needed. Lets go back to the example I just mentioned. Iclassmates 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,its 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 itslimit sentences to 20 words. Preferably less. You don’t need meaning. If youve 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 betterWordiness permeates a lot of documentation. A lot of thatwordiness is caused by loose and redundant writing. Two of While Im a stickler for writing tightly, there are situations inthe worst offenders, and the two that I dislike the most, are which you need to use a few more words. Lets look at thisThat is and In other words. example:© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 7
  8. 8. ... based on application status ● ClearIts short. But it sounds too much like developer speak, and it ● Concisereally doesnt sound natural. So, how about this instead: ● Consistent ... based on the status of the application ● CompleteIts slightly longer, but its not as clipped and makes a bit ● Correctmore sense. If you need to write longer sentences to achieve Then youre doing your readers a disservice.clarity, by all means do so. Documentation should be simple and designed for the needsSumming up of the user. The process isnt painless, but the goal of that process is within your reach. And its definitely a worthwhile goal.Documentation should be about showing users how to dothings. It should help take them from fumbling in the dark,put them on firmer footing and start them down the road tomastery. Technology book publisher Tim OReilly said it best: People are looking for advanced tips and tricks. Theyre not looking for the basics. Theyre looking for things that will give them more of an edge.Don’t bog users down with what’s not necessary for them toget things done in a fast and efficient way. With todaystechnology, no information goes missing. You just need tolink to anything that isnt in the main flow of yourdocumentation.Its the quality of the content and how its organized thatmakes your documentation successful. If it doesnt followwhat I call the 5 Cs:© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 8
  9. 9. Contact MeWeb site:http://scottnesbitt.netEmail:scott@scottnesbitt.netBlog:http://weblog.scottnesbitt.netTwitter:© 2009 Scott Nesbitt Keep It Simple: Streamline your documentation to make it more effective - 9