Software Documentation Introduction Documentation is a vital but often unappreciated part of almost every software product. Most software documentation is written by technical writers, employees who specialize in the field. People not in the field often fail to appreciate just how complex the process of writing documentation really is and how dependent it is on developers and other software professionals. There's also a lot of confusion out there about just what technical writing encompasses. Lesson 1: What is technical writing? The obvious answer to this question is any writing about technical subject matter, but that isn't the correct answer. Another glib answer is the writing of computer manuals but that too isn't quite right (although computer documentation is a very large subset of technical writing). I've seen the term "technical writing" defined as "any writing designed to aid the reader in the completion of a specific task or process". That too is correct but is so general as to be practically meaningless. Technical writing is really a cross of all of these things: writing meant to convey technical knowledge and how to apply it in specific situations to a very specific audience. In most cases that technical knowledge is operation of a specific piece of computer software or hardware and that audience is the person trying to use the same. Types of documentation Technical writers produce many different types of documents. The most visible documents are product manuals, books that accompany products to customers and instruct them on product usage. Online help consisting of a series of short instructional blurbs incorporated into the product itself is also common. Some technical writers never write any product documentation meant for external eyes but rather write product specification documents for internal use within the manufacturing company. Product specification documents are used to formally define what a product will do, its external interfaces (for instance, the type of menus and forms in the case of a graphical software application), and its internal interfaces (the available modes of communication from one part of the product to another; the functions front-end developers can use to access the underlying database in an application, for instance). This course will concentrate on software product manuals and online help but the material discussed will generally also apply to other documents created by technical writers. The importance of audience The audience is a key element that many people fail to consider. When your job is to convey knowledge to someone, you need to understand what that person already knows and develop a sense of the teaching methods likely to work for that person. If you're writing instructions for a customer service representative don't assume they understand database theory or any of the associated terminology. It sounds obvious, but the failure to properly analyze intended audience is the single largest pitfall facing technical writers. Consequently, we'll devote an entire lesson to audience in this class. The importance of word choice and consistent writing A good technical writer not only understands his intended audience, he understands the importance of clear and concise writing. Although most writers dream of beautiful prose that can move readers to another plane of existence, technical writing is all about removing any possible ambiguities so the reader understands precisely what to do. Short descriptive active sentences are generally better than long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any possible way an instruction can be misread or misconstrued someone will do so. When possible consequences of wrong actions are data corruption and data loss it becomes very important that users understand what you are telling them to do. Consistency is also important. If you lead your users to expect all functions to appear in boldface followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers may not realize that they're all functions and could get confused. Similarly, keep a similar style and vocabulary throughout each document. If you're writing an introduction filled with very general and basic conceptual material make sure you avoid as much technical terminology as possible and that you always define all terminology you do use. If several writers are collaborating on the same document make sure that individual voice doesn't shine through. When the document is finished you should not be able to tell where one person stopped and another picked up. You shouldn't even be able to tell that more than one person worked on the document. The importance of organization Technical writers tend to pay more attention to organization and the order material gets presented than most other writers. In many cases, other writers have some leeway in presentation. More often than not the material can be organized in several different ways and still retain its effectiveness. This is not often true for technical writing. Since much of the time you're either providing instructions - by their very nature a series of ordered steps - or providing background information that builds on prior material and tasks already completed organization is extremely important. If you fail to give users an essential step of any procedure they will not successfully complete that procedure. If you fail to discuss a basic topic before moving on to a related advanced topic they most likely will get confused. It's your job to analyze everything the user needs to do to successfully use a product and determine the order they need to do those items. Then you need to determine what the user is likely to already know and make sure that you provide every other scrap of needed information. In addition you must analyze how someone who doesn't understand the product as well as you do would think about the product and provide logical entry points to the necessary material given those expectations. It doesn't help to provide every scrap of information your users need if they can't find that information within your document. The importance of indexing Indexing is an important but often overlooked step in this process. Most users are going to either turn directly to your table of contents or turn directly to your index and start looking for the material they think they need. You need to make sure that information can be found from either method even if the user doesn't yet know precise terminology or an exact word to look up. Cross-indexing is an art, one that eludes many otherwise very competent technical writers. Indexing is a skill that needs to be developed and practiced regularly. The importance of editing and review You might think the process of technical writing is complete once you put the last word on the page, but it isn't. Every document needs to be reviewed and edited. In some cases you'll be fortunate enough to have an actual editor in place to edit your document, but most technical writers must rely on another technical writer or even do it themselves. In addition to the normal editing tasks of checking grammar, general word usage, and spelling, technical editing includes several other elements including checks for consistent word usage, checks that a consistent audience is maintained, and checks that the organizational choices make sense. Reviewing often occurs at the same time as the editing process but it serves a very different purpose. While editing ensures a clean grammatically correct document with consistent style, it doesn't test the accuracy of the content in any way. Reviewing does. If possible, you should have at least one of the developers who wrote the product participate in a review as well as at least one person who fits the target audience profile. If the person within the target audience doesn't understand everything you wrote then even if it's accurate you haven't successfully met your mandate and need to re-write the document accordingly. If the developer finds inaccuracies or points out areas where the product was changed then similarly you need to fix those before declaring the document finished. Lesson summary As you can see, technical writing is a complex process that involves a lot more than simply sitting down and putting pen to paper (or fingers to keyboard). The rest of this course will delve into many of the areas discussed here in more detail. By the time we're finished you should have an excellent understanding of the process from start to finish. Lesson 2: The Importance of Audience The audience is a key element that many people fail to consider. When your job is to convey knowledge to someone, you need to understand what that person already knows and develop a sense of the teaching methods likely to work for that person. If you're writing instructions for a customer service representative don't assume they understand database theory or any of the associated terminology. It sounds obvious, but the failure to properly analyze intended audience is the single largest pitfall facing technical writers. Examine the software to determine your user base If you don't understand your audience then chances are you won't be able to write documentation they'll understand. Evaluating your audience can be a difficult task but it is absolutely essential you do so. The best way to start analyzing your audience is by evaluating the product you need to document. You can tell quite a lot about your intended audience from the software since they are also the intended users of the software. If you're tasked with teaching developers how to write front ends for your product using Visual Basic, then you already know quite a lot about your audience. You know: They are developers They know Visual Basic They are familiar with user interface design In actuality, perhaps some of your readers will not fit this description, but it is your task to define the supported skill set, make it clear to your readers what you expect them to already know, and then write the book as if they know precisely that - no less and no more. If some of your readers do not meet all of the prerequisites you've set out for your book then it is their responsibility to gain those skills before attempting to use your book. In some cases, your intended audience will not be so clearly defined. Parts of your book may include overview information while other parts delve deep into the inner workings of your product. In these cases you'll need to work particularly hard to develop a list of things and terminology all of your readers will understand, and perhaps divide your book into several sections for analysis. Just be sure to clearly state who each section is intended for within your introductory material. Discuss the user base with the product manager It's all well and good for you to determine just who your intended audience is, but if the majority of people actually using the product differ greatly from your vision then you need to adjust your plans. Another way to determine who will be using a particular product is to discuss how that product is being marketed. The product manager is usually responsible for setting the requirements and marketing direction for a product. He or she should be able to provide a 30,000 foot view of what the product does and who should be using it. In general the product manager is in charge of the overall product that ships to users including the documentation. Although the chain of command may vary from company to company, you will most likely need the product manager to sign off on your documentation plans and on your final manuals. You may find that the product manager has a vastly different view of what the product does than you do. Product managers usually work in the abstract; they'll look at product specifications and the intended purpose of a product rather than what the developers actually made a product do when they built it. If you've based your vision on a working version of the product and it differs greatly from that of the product manager it is your responsibility to bring that discrepancy to his attention. Whenever possible, you should point out these discrepancies between plans and implementation to the developers and other interested parties as well as the product manager so that everyone understands precisely what is it the shipping product does regardless of intentions. Unless directly ordered not to do so, you should document what the product actually does rather than what it's supposed to do. Applying your audience analysis to your writing You should keep your view of the intended audience in mind at all times throughout your design and writing stages. As you're writing, think about what someone with that skill set and experience would already know about the topics you're writing about. Consider whether they'll be familiar with standard terminology or if you need to define every technical term you use. Organize your book in a way that will make sense to that audience. If you expect a particular book to be used as a reference, make sure each small piece of information is indexed and otherwise easy to find. If you're writing a conceptual overview of a topic, make sure either your intended audience should already know the topics leading up to that one or that you've documented those other topics before this one. Going back to our previous example of teaching Visual Basic developers how to build front end applications to our product, we know we can insert Visual Basic code into our documentation without much explanation, that we can assume the reader understands the concepts of data types, that the reader knows what forms are and how to move from one form to another, that they know how to create buttons, labels, and other controls, and that they understand how error handling works in Visual Basic. However, if our product makes various error messages available, I cannot assume the user knows these codes but I can assume they know how to implement them once I provide a list of codes and when they should be used. What happens if your audience analysis is wrong? Many of you probably didn't understand what all of the Visual Basic terminology I used in the last section means. That's because, most likely, you aren't Visual Basic developers. You weren't the intended audience described in that example, so you didn't have to understand what I expected Visual Basic programmers to understand. However, since you are the intended audience for this class and knowledge of Visual Basic programming is not a prerequisite, I should have defined those terms, or used more generic language to describe similar concepts. Because I didn't I left many of you scratching your heads wondering what I was talking about. This is bad. Your initial audience evaluation may be wrong for a number of reasons or, as in the case of the example above, there might be two audiences which have different backgrounds and knowledge bases. The best you can do is clearly define an audience and clearly state, up front, who you are writing for. In some cases, you may be given two audiences with very different requirements. For instance, you might be told that in addition to teaching those Visual Basic programmers what they need to know to write those front end applications, a particular chapter of your book will also be available as a sample to potential customers so they can evaluate the quality of the documentation. In that case, you need to keep both audiences in mind and, to some extent, write to the lowest common denominator. Even if there's only one audience you can still make mistakes. You might not have understood what the product does well enough to competently evaluate its intended audience. The product can change significantly after your initial interaction with it. Sometimes the overall documentation plan changes and you're stuck with a different focus than you were originally assigned. For instance, going back to our example, although originally you were supposed to write separate guides for writing front end applications in Visual Basic and in Java, the powers that be decided two months into your project to combine the two books. You've already written half of the Visual Basic book assuming everyone who reads it will know Visual Basic. Now it's your job to go back and determine what people who write front end applications in either Visual Basic or Java have in common and which items you'll need to explain better because only one group will recognize the terminology you used or because a specific concept exists in Java but not Visual Basic. Your conversations with the product manager, with other people working on other books for your product (assuming there are others), with developers who are writing the software, and with testers and other internal personnel trying to use the product will help you hone in on places where you don't write to the correct audience. Hopefully all lapses or changes of focus will be caught before your manual is actually read by real users. Lesson 3: The Importance of Word Choice and Consistent Writing A good technical writer not only understands his intended audience, he understands the importance of clear and concise writing. Although most writers dream of beautiful prose that can move readers to another plane of existence, technical writing is all about removing any possible ambiguities so the reader understands precisely what to do. Short descriptive active sentences are generally better than long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any possible way an instruction can be misread or misconstrued someone will do so. When possible consequences of wrong actions are data corruption and data loss it becomes very important that users understand what you are telling them to do. Consistency is also important. If you lead your users to expect all functions to appear in boldface followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers may not realize that they're all functions and could get confused. Similarly, keep a similar style and vocabulary throughout each document. If you're writing an introduction filled with very general and basic conceptual material make sure you avoid as much technical terminology as possible and that you always define all terminology you do use. If several writers are collaborating on the same document make sure that individual voice doesn't shine through. When the document is finished you should not be able to tell where one person stopped and another picked up. You shouldn't even be able to tell that more than one person worked on the document. Exercise proper word choice I often find myself muttering the famous line from The Princess Bride as I read books: "I do not think that word means what you think it means". Many writers have at least a minor problem with misused homonyms - using "their" when they mean "they're" or using "it's" instead of "its". It's important to have a good general grounding in language and grammar to avoid these errors. There are a lot of other problematic words that sound similar but have very different meanings. Selecting the incorrect one can really confuse your users. These are common pitfalls that befall most writers. Beyond general proper word choice, technical writers must be sure to develop a very precise vocabulary specific to the product or projects they're working on. There are many terms and names that have commonly been adapted by the computer industry; you must learn these conventions and use them properly so that readers can apply their previous knowledge to your books. If a particular type of GUI screen element is typically called a widget and you call it a whamboozle, not only do you not get instant recognition from people who know what a widget is, you could lead them to believe your whamboozle is not a widget (for otherwise you surely would have called it a widget). Most of us are taught in school to look for alternate ways of saying the same thing when we write. Unfortunately part of being a technical writer is unlearning habits our English teachers drilled into us for years. Technical writing exists solely to convey information. It is not meant to be pretty writing, writing that makes you sigh with pleasure just from the reading. It isn't generally meant to make the reader think about a host of ideas, sorting through their own views on controversial or confusing topics. Many of the constructs used in other types of writing simply aren't appropriate when you're writing documentation. Remember all those lessons regarding metaphors and simile? Purge them from your brain. If you're writing for clarity above all else it is important to use the same terminology over and over again. If you refer to a particular nameless part of your product as a wombeezil make sure you use that term over and over again rather than trying to come up with fancy terms and descriptions solely for the sake of adding variety to your writing. There are entire books devoted to defining common computer terminology and common usage of terminology in documentation; I cannot go into all of even the most common issues here. I strongly recommend referring to the Microsoft Manual of Style for Technical Publications for more information on this and other style concerns. Unfortunately, the book is currently out of print so you may have so difficulty locating a copy. Use short active sentences Traditionally technical writers are told to always use short active sentences. This is good advice, but writers today are generally granted a bit more leeway than those of twenty years ago. Short active sentences still communicate instructions better than passive or long sentences - they leave less room for ambiguity or misinterpretation. However, some passivity and longer sentences are generally allowed within conceptual material (depending on your editor and group style rules). In all cases, extraneous words should be removed. If your sentence makes sense without "the fact that" then delete that phrase. Extra words just give people more ways to misconstrue your meaning. Use a consistent voice Voice in writing is a nebulous thing. It's difficult to quantify and can be even more difficult to control. Voice is essentially the tone of the writing. Most educational books are very formal and dry, often concerned with testing or expanding the vocabulary of those reading. Most fiction tries to be true to one character, picking up his or her mannerisms and attitudes and showing them on paper. There is no one proper tone for documentation beyond the need for consistency. Readers may not specifically think about voice, but a sudden change from friendly to terse will be noticed and detract from the reader's ability to focus on the information provided. Many people feel a dry academic style works best while others prefer to be friendly and use simple language. Some types of documentation are best suited for a specific tone - introductory material generally works best with friendly inviting language and reference material is more geared toward short, terse language - but in general it doesn't matter what voice you use as long as it's consistent. Develop a consistent style A lot of different elements combine to define a style for your writing. In general terms a writer's style encompasses things like voice, word choice, the use of formatting, and other similar elements. It's the overall package, if you will. When technical writers discuss style they generally concentrate on word choice and on the formatting and presentation of material - how different product elements are capitalized and typeset, how chapters are paginated, how indexes are formatted, and similar concerns. Most writing groups have their own style guides that cover that departments views on the spelling of certain ambiguous words (email vs. e- mail, for example). Often they select a particular book then add or change specific elements to suit their needs. The Microsoft Manual of Style for Technical Publications is the most popular choice, for good reason. It's the most comprehensive guide I've seen. By starting with this (or another) book and just modifying its rules to suit your needs, technical writing departments can save a great deal of time and effort. These customized sections (or full, independent style guides) should contain lists of product-specific words and their acceptable usage as well as departmental rules for comma usage, preferred choice when there are two acceptable spellings of a word, and your choices for capitalization, bolding, and italicizing. This last part is particularly important when documenting a programming language or tool - there are so many different elements in a language and your readers need to know, at a glance, whether you are discussing a function or a query (for example). If you're writing alone, you probably don't need a formal style guide as long as you can be consistent. If you find yourself wavering, or if during the editing process you notice a lot of variation in word choice or formatting, then take the time to write a short personal style guide. Make sure you actually refer to it when writing - its mere existence will not add consistency to your writing. Style guides and issues related to style can be among the most divisive in any writing group. Everyone has their own ideas on what is proper and right, and often those ideas conflict with each other. It's almost certain that in any group situation you won't like all of the decisions, but it's important that you abide by them. Maintain consistency in collaborative projects It is especially important to maintain a consistent voice and style when more than one writer works on a single document. Readers should not be able to tell which parts of a book are written by one writer and which by another, or even that more than one writer worked on the book. Minor deviations from the accepted style may not be noticeable in a book written by one person (as long as they are consistent) but if two or three different people each differ from the standard in different ways it will be noticeable and distracting to the reader. One way to avoid such problems is to require each writer to read and edit those chapters or sections written by the other writers. If one of the other writers does something consistently different from the way you do it, it should be very easy to spot. Once these problem areas are identified you as a group can determine the best way to fix them and provide the needed consistency. Lesson 4: Writing Procedures Most technical writers spend at least part of their time writing procedures. Procedures are essentially detailed instructions for performing one or more tasks. Unless your documentation is strictly conceptual (explaining a topic rather than telling your readers how to use the software), you will need to write procedures. Since readers will be following your instructions on real applications with real data, it is particularly important that your directions be clear, concise, accurate, and easy to follow. Use active language A procedure tells your reader to perform a specific action or set of actions. Good instructions use active language, commanding the reader to act rather than discussing actions that have been taken or could be taken by others. There's a big difference between saying "the dropdown box in the corner of the page can be used to select the date" and "select a date using the dropdown box in the corner". The first informs your reader what that particular dropdown box does and the second tells them to do it. The text introducing a procedure can discuss when to perform the procedure; the procedure itself needs to tell the user how to do the needed actions and assume that they are, in fact, doing them. Use short phrases and sentences It's important to give each instruction as clearly as possible. The fewer words used to convey a particular task, the less places there are for a user to get confused. Anyplace you can use a single word to convey an action, do so. Avoid any elaboration or explanation within the procedure itself. If you need to provide options or explain why a particular task is important, do it in paragraph form before you begin the procedure. If the user can choose more than one way to perform a specific task, present each procedure separately after explanatory text discussing when that particular option is a good choice. Use ordered lists By definition a procedure consists of a set of tasks that need to be performed in a specific order. By presenting these tasks in an ordered list, with steps 1, 2, 3, etc., you reinforce the need to follow a set order. Numbered lists have an ingrained implied order that's almost subconscious and thus provide much stronger impetus that simply supplying paragraphs filled with "Do this then do that" terminology. Ordered lists also help you bone down the language to its simplest, and thus clearest, form. By removing all of the extraneous connective words needed to indicate order in paragraph form you remove verbiage that could confuse your readers. Provide one instruction per step One of the common mistakes people make when writing procedures is trying to stuff several steps into one line. They think that each instruction is simple so they can safely combine a few easy directions into one combined step. Unfortunately no matter how simple those individual instructions are, any step that tells you how to do more than one thing is potentially confusing. Avoid that confusion by limiting each step to one instruction no matter how simple or mundane. For instance, when telling users how to create a new account you could say: 1. Enter the desired username and password into the appropriate fields 2. Select the desired permissions for the new user 3. Hit enter to add the user but this is clearer: 1. Enter the desired username in the username field 2. Enter the desired password in the password field 3. Select the Read checkbox if this user has read privileges 4. Select the Write checkbox if this user has write privileges 5. Select the Exec checkbox if this user has execute privileges 6. Hit enter to add the user Be consistent Consistency is important in all documentation, but especially so when writing procedures. In particular, it is paramount to use consistent names for screen elements like buttons, forms, tabs, and windows. Many of these elements won't be named within the software so you'll have to name them. Choose a logical name that makes it obvious what particular element you're referring to and then propagate that name throughout the entire documentation set. Collect all of the names you create and make sure they're added to a common database of product terminology. In an ideal world, these terms would be added to a group style guide or glossary, but even if you don't do that, make sure they are preserved and available to everyone working on that product. Don't feel like you need to come up with ten creative ways to tell people how to press a button. Tell them to press the button (or tap it, or choose it, or whatever terminology you've decided on) each and every time. You shouldn't break out the thesaurus, but rather use repetitiveness to really pound home clarity. In addition to consistent use of names and terminology in general, it's also important to use parallel constructs within your procedures. The human brain looks for parallelism and is bothered when it's not there (even if it doesn't completely understand what's wrong with a particular sentence). By beginning each step with a similar phrase and tone, you're allowing the user to ignore the writing and concentrate on the content. Perform the acts you're describing A sure way to provide incorrect instructions is to rely on your memory when writing procedures. Even if you've performed a task hundreds of times, you will always forget one small step or provide wishy- washy directions at some point along the way because you can't quite remember if the menu item is named "Remove all users" or "Delete users". If you're overly familiar with a procedure you are also prone to leave out steps or combine multiple steps into one gigantic step that's confusing to someone not as familiar with the process as you are. For instance, most of us know how to save a file. Let's assume you're all using Mac OS X Jaguar writing in TextEdit (since that's precisely what I'm doing right now and I always heed my own advice of doing what I'm describing). I could assume you understand the basic idea of how to save a file and provide this procedure for saving files: 1. Save the text file in the location of your choice But in reality what I want you to do is: 1. Select the File|Save As menu item 2. Name the file in the Save As text area 3. Select a location from the Where dropdown box 4. Press the Save button or alternately: 1. Select the File|Save As menu item 2. Name the file in the Save As text area 3. Navigate to the location of your choice using the directory viewer 4. Press the Save button Now most of that should be self-explanatory, even if you've never saved a file in Jaguar before. But people learn and extrapolate at different rates and by spelling out precise directions I've made sure every reader will be able to follow my instructions quickly and without much experimentation. Lesson Summary There's no question that the ability to write clear and correct procedures is absolutely paramount for anyone writing software documentation. It's also true that there are a lot of rules. The good news is that most of us have a lot of practice with procedures. We may not call them procedures, but we encounter sets of instructions all of the time in daily life in everything from recipes when we cook to driving directions when we travel. Thus we all have an inborn recognition of procedures and an inherent understanding of how they work. You just need to add common sense and good writing skills to that understanding and you'll be able to write your own clear and easy to follow procedures. Lesson 5: Using Tables and Graphics As a technical writer your job is to convey information to your readers. Sometimes the best way to do that is by writing long descriptive passages. Sometimes the best way to do that is by providing short, easy to use procedures detailing precisely how to perform important tasks. But sometimes you need to provide a screenshot or a graphical representation of an idea before it can really gel for your readers. Part of your job is judging when to rely solely on words and when to provide a graphical illustration of the information you need to impart to the reader. Using tables Many people today think of tables as layout tools, tools to help present information in pretty columns. Although tables are often misused in this fashion, they are not meant to be an underlying layout tool. Rather, their purpose is to present tabular data clearly and understandably. What is tabular data? Tabular data is any collection of data that most logically fits into a matrix. This is most often a series of elements which each have multiple properties. For instance, you could have a series of error codes and their corresponding text messages. You could present these as a list, but if you present them in a table you don't need as many descriptive words and the two parts of each error - the code and the message - are visually separated and easy to identify at a glance. To illustrate this example, let's display a list of errors and then a table containing the same information. First the list: Error 190 occurs when you run out of memory Error 200 occurs when your input value falls out of the allowed range Error 300 occurs when you cannot connect to the database And now the table: Error Code Error Message 190 Out of Memory 200 Out of Range 300 Connection Error As you can see the table is a lot easier to parse. Imagine if each of the elements in the collection had four or five different properties. In this example, the errors could also be categorized by error type and you could also note whether the error message can be localized. The list would get a lot more dense and complicated, while the table would remain relatively easy to read: Error 190 occurs when you run out of memory. It's a basic system error that can be localized. Error 200 occurs when your input value falls out of the allowed range. It's a parameter error that cannot be localized. Error 300 occurs when you cannot connect to the database. It's a basic system error that cannot be localized. or within the table: Error Code Error Message Error Group Can Be Localized? 190 Out of Memory System Yes 200 Out of Range Parameter No 300 Connection Error System No As you can see, tables really do make a big different. Use them judiciously, but use them whenever you need to present a collection of tabular data. Using screenshots Sometimes a picture really is worth a thousand words. No matter how well you describe the user interface of a product, there's really no replacement for showing your users what it actually looks like. You need to describe things too - screenshots aren't a replacement for proper discussion - but sometimes an illustration can help your text make more sense. As with tables, you don't want to overuse screenshots. If an entire section is devoted to the same tab of your application, you generally don't need to present a visual image of that tab every time you ask your users to do something within that tab. If you present the same picture six times within a single procedure it merely serves to slow down the process, spread the information out over multiple pages, and interrupt their train of thought. In general unless they are small graphical representations of buttons or active screen elements, it's best not to include any screenshots or other illustrations within a procedure. Provide any necessary graphics before you get into the procedure so your users can refer to them as needed without having them interrupt the procedure itself. Using representational drawings Just as screenshots can help your users better understand procedures and how to navigate through the user interface of the product you're documenting, representational drawings can help them understand conceptual material. Spending three pages describing the product architecture in detail is all well and good, but without a diagram showing how your application server sits above the database but behind the web server even a lengthy description may not register with your users. Again, as with screenshots, representational drawings cannot take the place of the actual written discussion. Without text to frame the drawing your users won't know what they're looking at or why they should care. You need both elements working in concert. Writing captions Although not absolutely necessary, most product manuals provide captions for all graphics including drawings, screenshots, and tables. These captions provide a short catch-phrase that tells your users what they'll be seeing in the graphic. It's sort of an extra reminder of what they should be thinking about when they look at the table or picture. Captions tend to stand out more than the general text surrounding the graphic so you can find a little bit of information about a graphic without having to scrounge around the nearby text. If you've arrived at the page to see that particular table or figure rather than to read the section of text, this can be a real timesaver. Table of Figures and Table of Tables Most books provide a Table of Contents to help readers understand what material is covered within the book and to help them quickly go directly to a specific piece of information they need. Many manuals also provide Tables of Figures and Tables of Tables for the same reason. Usually found immediately after the Table of Contents, these two listings generally list the figures - screenshots and representational drawings - and the tables within the book using their captions as descriptors. These tables are not as widely used by readers as the Table of Contents or the index, but they do provide an alternate route to quickly find specific information throughout the book. They also give the reader a sense of which concepts are most important in a book. Because the Table of Contents lists everything within a book, it doesn't give you any sense of what the key areas are. It's all listed and treated equally. But if a concept is important enough to warrant a representational drawing the reader knows it's something you particularly want them to understand well. Lesson Summary Graphics - screenshots, representational drawings, and tables - are an important part of technical writing. The key is to use them appropriately. Determine when they are needed and when they aren't. Make sure they fit the topic you're discussing and that you provide a short but informative caption for each graphic. Most importantly, make sure that you don't add graphics just for the sake of having pretty pictures in your book. Lesson 6: Indexing Your Documents It's your job to analyze everything the user needs to do to successfully use a product and determine the order they need to do those items. Then you need to determine what the user is likely to already know and make sure that you provide every other scrap of needed information. In addition you must analyze how someone who doesn't understand the product as well as you do would think about the product and provide logical entry points to the necessary material given those expectations. It doesn't help to provide every scrap of information your users need if they can't find that information within your document. Indexing is an important but often overlooked step in this process. Most users are going to either turn directly to your table of contents or turn directly to your index and start looking for the material they think they need. You need to make sure that information can be found from either method even if the user doesn't yet know precise terminology or an exact word to look up. Cross-indexing is an art, one that eludes many otherwise very competent technical writers. Indexing is a skill that needs to be developed and practiced regularly. Deciding what to index It can be very difficult to decide which words to index. You don't want or need to build a complete listing of every word in your manual yet at the same time you want to make all of the important information within easy to find for every person reading the book. A good place to start is with section headings. If an idea is important enough to merit a section heading it's probably important enough to merit an index entry. A chapter discussing building clients in Visual Basic might cover topics such as the available objects, error handling, and debugging. The first pass at indexing that chapter might include the following entries: Debugging in Visual Basic Developing Visual Basic Clients Error Handling in Visual Basic Objects in Visual Basic Visual Basic Clients That's certainly a start, but those five entries aren't going to effectively lead people to everything they need to know about developing client applications in Visual Basic. That will probably be enough to lead any user to the general section on Visual Basic, but a user looking for information on a particular object may not think to look under Visual Basic. After integrating major headings, the next step is to look at the information covered by each and determine which pieces of information users are most likely to specifically seek out by name. Most likely users will want specific information on individual objects. If the chapter discusses four objects - OurFactory, OurBean, OurStream, and OurText - then those should each be indexed as well. Basically during the indexing process you should return to your audience analysis and really think about what users will want to do with the information you provide and the background they bring to the table that will lead to the terminology they use to look for that information. Choosing which instances to mark The words "error handling" might appear three times in every paragraph within the error handling section. You don't want to include separate index entries for each instance - that would be overkill and lead to a cluttered, difficult-to-use index. If your indexing supports page ranges, you could decide to include the entire range of the chapter within a single index entry. If your index only allows single page entries, then you'll need to determine if marking the first page of the section is sufficient or if you need further markers at important points within the section. Perhaps a more complex situation is when you discuss a concept in a chapter overview and then provide full details a page or two later within the chapter. You'll need to decide whether it makes sense to index either places or just the area where you provide the detail. This is your choice, and you'll need to decide what makes sense for your book. Build in redundancy Once you've chosen the topics and terms to index, you might think you're almost done with your index. You would be wrong. Not every reader thinks the same way and simply including a single entry for an importance concept isn't enough. If there are alternate terms use them. For instance, in our Visual Basic chapter above, include the common abbreviation for Visual Basic - VB - in the index. Think of alternate terminology people might use when saying "developing clients" and provide index entries for them. Do the same for other words and phrases. If you don't use that terminology at all within the book, use a "see" reference to indicate that it's covered under another name. We came up with five base index entries for the Visual Basic chapter above. Adding in redundant and alternate entries, we might get the following entries: Building Visual Basic Clients Clients, Visual Basic Clients, Visual Basic, Available Objects Clients, Visual Basic, Debugging Clients, Visual Basic, Error Handling Debugging, Visual Basic Developing Visual Basic Clients Error Handling, Visual Basic Exceptions: see Error Handling Objects, Visual Basic Throwing Exceptions: see Error Handling VB Clients: see Visual Basic Clients Visual Basic, Available Objects Visual Basic, Debugging Visual Basic, Error Handling Visual Basic Clients As you can see, this gives the user many more ways to find that same information they need. Consistency in Indexes Just as it's important to be consistent throughout the text of the manual, it's also important to provide consistent index entries. If you normally capitalize all words in an index entry, make sure you capitalize them in every single entry. If you generally include three variants on each object, make sure each variant is included for each object. You'll also want to be consistent regarding which occurrences of a word or phrase to include in the index. If your chapter has a general overview that briefly discusses each major topic then later sections on that discuss those topics in detail, either index both locations for every term or don't index both for every term. Don't index some of the words in the overview and some just in the detailed sections that follow. When to build your index Many people recommend doing all of your indexing at the end of the writing process. This is a holdover from the time when indexing had to be done by hand and the simple shift of a single page could invalidate most of your work to date. In these days of automatic indexing and markers that move with words as they shift locations there really is no technical reason to index at the end of the process and many people choose to index as they write. There are advantages and disadvantages to either choice. Indexing as you go definitely slows down the writing process, meaning it will take longer before you're reading for editing and review. Many people find the resulting stop and go writing process prevents them from properly concentrating on what they're writing and thus won't index as they go. If you index at the end of a tight schedule, you can do your indexing while others are editing and reviewing your book, then give the editors your index once they hand back the rest of your book. Leaving the indexing to the end of the writing process can lead to a very rushed and often inferior product. Most non-writers fail to understand the importance of a good index and it's more difficult to get a product manager to give you more time to index a book than it is to get more time to write the last two chapters. On the other hand, indexing as you go is more likely to lead to inconsistencies as you could make different choices regarding capitalization or marker placement or other index features during different phases of the indexing. These problems should be caught during the editing process. If you index as you go, be sure that someone edits the final result with an eye toward consistency. Another alternative is to index each chapter or major section after it's finished. This allows you to write major chunks of text without constant interruption and still avoids the rush of trying to fully index a book when time is running out. It can still lead to some consistency problems, but again these should be caught during the editing process. Lesson 7: Editing And Reviews You might think the process of technical writing is complete once you put the last word on the page, but it isn't. Every document needs to be reviewed and edited. In some cases you'll be fortunate enough to have an actual editor in place to edit your document, but most technical writers must rely on another technical writer or even do it themselves. In addition to the normal editing tasks of checking grammar, general word usage, and spelling, technical editing includes several other elements including checks for consistent word usage, checks that a consistent audience is maintained, and checks that the organizational choices make sense. Reviewing often occurs at the same time as the editing process but it serves a very different purpose. While editing ensures a clean grammatically correct document with consistent style, it doesn't test the accuracy of the content in any way. Reviewing does. If possible, you should have at least one of the developers who wrote the product participate in a review as well as at least one person who fits the target audience profile. If the person within the target audience doesn't understand everything you wrote then even if it's accurate you haven't successfully met your mandate and need to re-write the document accordingly. If the developer finds inaccuracies or points out areas where the product was changed then similarly you need to fix those before declaring the document finished. Working with an editor If you work in a large organization chances are you'll have one or two editors who need to sign off on your documentation before it’s published. These editors check your books for spelling mistakes, incorrect grammar, flow, and other general common writing problems. They also check for proper use of trademarks, adherence to the corporate style, consistency, widow and orphan lines, pagination issues, and other features that might be specific to your particular company or department. You might think proper grammar provides a concrete set of rules that leave no room for interpretation but that's not the case. The hardest part of working with different editors is that each has his or her own slightly different interpretation of the rules. The rules regarding commas, for instance, are flexible. I've worked with editors who saw commas as the enemy and eliminated as many as humanly possible without altering meaning and I've worked with people who prefer to include commas every single instance it's possible to do so. Both are correct - it's all a matter of preferred style. Until you learn the style of a new editor expect some growing pains. The single most important thing to remember when working with editors is that they do not, in general, understand the subject matter of the books they're editing. They do, at times, unwittingly suggest changes that alter your meaning. It is your responsibility to go back to the editor and point this out. Just because an editor requested a specific change does not automatically mean you must make it. If it's a bad change in your opinion, discuss it with the editor and explain why you feel your way is better. Any editor worth their salt will sacrifice their rules or strictly correct grammar for accuracy. Peer editing Smaller groups often don't have any editors but rather institute peer editing. Once your book is finished (or once specific sections are finished) you give them to another writer in the group for critique. Again, the main purpose is to ensure correct spelling, correct grammar, and adherence to the group style. In some cases the writer editing your work will know nothing about its subject but in others the writer may indeed know the product quite well. In those cases, you'll most likely get comments on the content in addition to actual editing. This amounts to an extra reviewer and content-related comments should be treated as review feedback. Peer editing is usually an informal process leaving you the option to integrate or ignore the results as you see fit. It's less like to catch small errors or minor deviations from the accepted style than a formal edit. Writers have varying experience with editing and sometimes the best writers are not the best editors. If you work in a group for a long time you'll get a feel for who the better editors are and, hopefully, be able to give them your books for editing. Self editing If you work alone, work as a contractor, or sometimes if you're in a small group there isn't anyone else available to edit your work so you have to do it yourself. Editing your own work is very difficult because you know what you're trying to say. You have extra context clues and background to fill in any blanks that might actually be in the writing so it's easy to miss mistakes or omissions. If at all possible, leave a little time between the completion of the writing and the beginning of your editing process. This gives your brain some time to forget exact word patterns and helps you catch more problems with the writing. If you can, it's best to work on another project in between the writing and editing steps. Reading your work out loud can be a very effective self-editing tool. Your brain is less likely to fill in missing words if you're trying to vocalize them. Any awkwardness or odd pauses in the writing are also more apparent when read out loud. Why reviews are important Technical writers get their information in a number of different ways. Many software products are described in specification documents well before their first line of code is written. These documents serve as a starting point for everyone working on the product - developers, technical writers, and testers alike. Often cross-functional teams have ongoing meetings to access progress and discuss changes to the product. Developers, product managers, and other involved parties send emails back and forth containing product information and suggestions. As a technical writer it's your job to be a fly on the wall at as many of these conversations as possible. Get yourself on every email list you can. Get invited to those boring meetings. If you're lucky, you can also be an early alpha or beta tester of the product and see how it works first hand. Even if you get a constant stream of emails, go to three meetings every week, and get the chance to use the product to your heart's content, there will be last minute changes to the product. There may be earlier changes that you don't know about or that never came up in any of the meetings. Some developers may not be forthcoming with changes or your product manager may forget that you need to know a particular piece of information. Even if you have all of the information, you may have misinterpreted something or not fully understood everything you read or heard. The review process is a check built into the documentation process to catch all of those omissions and changes and mistakes. Dealing with difficult reviewers Some people are more cooperative than others. It's a fact of life. As a technical writer you need to deal with a lot of people who don't necessarily see helping you as part of their job description (even when it should be). Some people will be very forthcoming when you ask them questions, others will practically need to be tied down before they answer you. Similarly when sending material for review, some people will comply and give you the necessary feedback in a timely manner while others won't. If a particular developer isn't cooperating with a review request, notify your manager and ask for his or her help. They may suggest you discuss the obstruction with the reviewer's boss or have other suggestions to elicit cooperation. If you can, find an alternate source of information - if a developer isn't cooperating perhaps the person testing those features or a consultant using them will. Ultimately as long as you tried to get your material reviewed, it's not your fault if there are technical inaccuracies. Unfortunately this doesn't help the customers getting confused by the mistakes so you should make every effort to get the needed feedback. Integrating review comments At the end of a review cycle you'll most likely have several sets of feedback on the same material. Sometimes the comments will conflict, sometimes they may not make sense. More often than you'd like they'll point out deficiencies and missing information. You can also get off the wall review comments or run into a reviewer who feels it important to correct the grammar and writing style of your book, often doing so without checking the technical content. As with the editing process, when it gets right down to it, you are in charge of the document and you decide which comments are helpful and need to be addressed in the documentation before it's released. Corrections can generally be made within a few days, barring long discussion of conflicting comments, but vital information that simply isn't documented cannot usually be added so quickly. If your release date is nearing and a reviewer insists that a new chapter is needed, you may not have time to research and write this new information. At that point it's your responsibility to inform the product manager of the request to add more information and explain that it cannot be completed within the current schedule. He or she can then determine whether the projected completion date is strict or if you can have more time to add new information. It is unlikely that the product release date will be altered just so you can add more documentation (although it has happened to me twice) so this determination will generally be based on the current state of the product itself. If you make extensive changes after the first round of reviews, you may want to ask for another round of feedback from your reviewers. At the very least, you should send the changed sections to the reviewers who suggested the changes so they can sign off on the modified information. Which comes first - Reviewing or Editing? In general, editors like to be the last person to see a book before it's released. If you have actual editors chances are you'll want to go through the review process before the editing process. Alternately, if you're fairly confident that there won't be massive changes needed after the review, you could propose simultaneous review and edit periods. You could then offer the finalized, post-review document to the editors for a brief final edit to ensure you didn't violate standards when you integrated the review comments if that would make them more comfortable. Lesson 8: The Tools of the Trade Although there are a wide variety of tools you can use to create documentation, most writers use a few core applications for most of their work. Some documentation is written in Microsoft Word and some in other word processors, but most technical writers use Adobe FrameMaker to write printed books. Tools like Quadralay WebWorks and Adobe Acrobat can take that FrameMaker output and generate HTML and PDF files for end users and professional printers. Online help can also be written using a variety of tools but most technical writers use RoboHelp. This lesson isn't going to make you an expert in any of these products or even give you a sense of their power and versatility. But it will give you a taste for each of the popular tools and why they're helpful when writing software documentation. Why not Microsoft Word? Most people use Microsoft Word for the majority of their word processing needs. It's perhaps the most pervasively used product on the market. A lot of people want to know why they can't just keep using Word when they start writing documentation. The short answer is that you can but you probably shouldn't. There are plenty of technical writers who do use Microsoft Word to write documentation. It has enough rudimentary word processing features to permit effective output of short documents and can generally be massaged into handling mid-sized or even long documents to some extent. But it lacks many of the features of FrameMaker that make it a more powerful option. For one thing, Microsoft Word doesn't have any concept of books. You just have one or more documents that, as far as Word is concerned, are independent files. You are responsible for maintaining consistency among the table of contents and index. You are responsible for making sure all of the files are kept together, maintain a common style and format, and fit into a single book. Word also provides very limited control over layout and style. For the most part, all files created in Word look the same. It's very difficult to personalize and give your documents a specific corporate look and feel. What FrameMaker offers that Word doesn't FrameMaker is designed from start to finish as a tool for creating books. It understands the book as an object and that every book contains a subset of lesser elements like a table of contents, chapters, an index, sections, illustrations, and others. It gives you the control to organize your book in a sensible order, adding and reordering files at will, without the need to figure out which order to place files each time you work with the book. FrameMaker has the concept of a cross reference, sort of like a hyperlink, that lets you pull chapter and page citations (or even paragraphs or sentences) from one place in the book and reference or include them in another. These cross references are then automatically maintained - if the original text changes its location or content the appropriate changes are automatically made in all references. One of the main advantages to FrameMaker is the level of control it gives you over the appearance of your book. I mentioned above that one Microsoft Word files end up looking pretty much the same as all other Word files. With FrameMaker you can control exact layout of every type of page element. You basically start with a blank page and can determine exactly how your book will look from there. In actuality most Frame users do not ever see that blank page - someone has already made all of the difficult choices for them and created a template to make it easy to implement the desired look. Although Microsoft Word does have a concept of templates they are very basic. FrameMaker templates capture every nuance of appearance and available formatting making consistency much easier. Generating paper documentation Once you've finished writing your book you still need to get them to your customers. Books can be distributed as traditional paper books or in various electronic formats, most notably in either PDF or HTML. Since your book exists only in FrameMaker at this stage, you'll need to convert it to these other formats. Paper books are generally sent to a professional printer for mass production and binding. Almost all printers request high-quality PDF files from writers. You can use a full version of Adobe Acrobat (as opposed to the more common Adobe Acrobat Reader) to create PDF files from FrameMaker. Adobe makes this conversion very easy - as simple as selecting a new printer and printing the file with the "Save as File" option checked (this can also be done using "Save as PDF" although in some cases this doesn't work as well). However, most printers require certain settings to be used while generating the PDF files. You'll need to check with your printer and get a list of settings they want you to use - each printer varies slightly. These settings can be changed in the Adobe Acrobat Distiller portion of Acrobat. Once you've done this, creating PDF files for printing returns to the simple process of printing the Frame file. Generating electronic documentation HTML and PDF are the two most common formats used for electronic documentation. Although you can distribute PDF files meant for printers electronically, most people choose to make hyperlinks active and add a table of contents to the PDF file first. This involves a few changes to the Distiller settings and some minor editing to the resulting PDF files. The last few versions of FrameMaker have included a "Save as HTML" option but frankly it's not yet up to snuff. The generated HTML has a lot of problems and needs quite a bit of editing before it looks nice enough to send to customers. While this quick and dirty HTML generation is wonderful for internal reviews and beta testing, most people choose to use Quadralay WebWorks to generate HTML for actual release to customers. Quadralay isn't perfect either, but it's a more robust option than the simple FrameMaker HTML conversion. Quadralay works by mapping available page elements - headings, tables, footers, code samples, and the like - to an appropriate HTML tag. For instance, first level headings in your Frame files will generally be placed between <H1> tags in the resulting HTML. Not all mappings are so obvious, and Quadralay lets you choose exactly how each element is converted. You could, for instance, choose to start a new page for each first level heading rather than assign them as <H1>. Quadralay also automatically generates next and previous links for each page as well as a table of contents. The Great Tool Search Just because something is the most popular tool used by technical writers doesn't mean it's the best tool for you to use. Look around and see what the options are. Try a few out, if possible, then choose the one that's right for you. There's more to life than just writing - from time to time almost all technical writers need to create technical diagrams, take screen shots, edit HTML files, and do other tasks beyond strictly putting words on the page. Each of these tasks will involve using other tools and sometimes finding simple, easy-to- use tools for these secondary tasks can save an enormous amount of time. Part of being a technical writer is keeping up with trends and with the tools of the trade. The tools discussed in this lesson will provide a nice starting point, but ultimately you'll need to form your own collection of applications needed to get your job done. Class Summary - What should you take away from this class? This has been a densely packed class filled with a lot of information. This summary will reinforce the most important points to take away from the experience. Software documentation has a lot of elements. You can't just sit down and start randomly writing about the product you're documenting then stop when you think you're done. You need to analyze your readership and keep their needs, background, and experience in mind as you plan and write your documentation. You need to carefully choose wording and always write as clearly as possible. You need to understand when to include a figure or table and when it's best to present information strictly textually. You also need to understand your book and your audience well enough to effectively index the subject matter. You need to respect style guides and formatting decisions made by others you work with even if you don't agree with all of those decisions. You need to forge a good working relationship with developers, testers, and other software professionals. You need to accept feedback and accept that the product you're documenting will change. Most of all, you need to enjoy using software and teaching how to use it to others.
Pages to are hidden for
"Software_Documentation_Notes"Please download to view full document