What is a User Guide? A User Guide explains how to use a software application in language that a non-technical person can understand. In general, user guides are part of the documentation suite that comes with an application for example, Data Sheets, Release Notes,Installation Guides andSystem Administration Guides.
Writing techical manuals should not only include manual writing. Even better still: writing technical manuals should preferably not entail writing manuals. If a picture tells you more than a 1,000 words, the illustration should take preference. An illustration can be far more effective if you want to get your message across. If you are writing a technical user guide or process documentation for e-learning purposes, or for archival in your organization’s server, a good training manual should be easy to understand, intuitive enough for the viewer to manoeuvre through and well sectioned for easy reference. Looking for tips on writing user manuals? A lot of user manuals will leave people stumped therefore not solving the problem the manual is supposed to solve. Writing user manuals can be a difficult task, and yet you want to ensure that the user manual you write actually helps someone and is user friendly.
Technical Writers will often create a Documentation Plan before writing their user guide. This defines the scope, size, delivery format and resources required to produce the actual user guide.
As the name implies, User Guides are written to help people understand an software application or IT system. They are also called User Manuals. When writing a User Guide, use simple language with short sentences. This writing style helps the user understand the application.
Our User Guide templates can be used to create user guides, user manuals, getting started guides and other types of technical documents. A User Guide is an online or printed book that describes how to use a software application.
User Guides are the first port of call when something needs to be read. As many people read user guides when frustrated and after having lost patience with the software, you need to write your material to address their concerns quickly.
User Guides are often written for non-technical individuals. The level of content and terminology differs considerably from, for example, a System Administration Guide, which is more detailed and complex.
This rest of article offers some guidelines to consider when writing your User Guide, such as:
Identifying your audience
Writing sections
Defining style guide and standards
Delivery formats
Identifying Your Audience
As with all types of writing, the first step is to define your TARGET AUDIENCE. Your target audience are the people who will user your document. As different readers have different requirements, you need to consider their specific requirements. Use this template to learn more about the target audience for your projects and what they want to achieve, for example, read your user guide, visit your website or buy your product.
The worksheets include 130 points you can use to capture demographic date so that you have a more holistic view of their wishes, desires, fears, and preferences.
Identify the target audience
Identify their level of technical knowledge
Identify how they will use the guide
Audience Definitions
In the planning process, develop an audience definition that identifies:
The user
The system
The tasks
Software is used to do specific things. Users want to know what the software can do for them, for example, how to print a page in landscape.
They are generally not interested in the nitty-gritty technical details; they want to click a button and get a result. The User Guide is to teach them how the software helps them to do something.
Depending on the guide in question, you may need to address several audiences. For example:
Programmers who will troubleshoot the program
IT Managers who want to know the resources the program requires
Project Managers who want to confirm that the original requirements were met.
If you are writing for more than one audience, develop an audience definition for each one. Examine the definitions and see if you can address all audience types with one document. In many situations, you may need to write a number of documents, of which the users guide is only one.
When planning, use the audience definition to focus your decisions.
When writing, the audience definition serves as a guide for the documentation team and as a benchmark for evaluating the results.
Here are some questions that will help define your audience's needs:
Where will they use the document, for example, in the office, at home, in their car?
How much experience have they of using your application?
Is this guide an upgrade to an existing application?
Is your application new? If so, you may want to include a Getting Started document to introduce the software.
How will they use the user guide?
Will they install the software by themselves or do so over the internet?
What level of detail is required?
Will graphics help their understanding of how to use your product?
Writing the User Guide
Each user guide is comprised of front page, body sections, and a back page. The following section describes what each of these needs to contain.
Front Page (cover pages)
Include a cover page, table of contents, and a preface, if necessary.
Cover and Title Page
If the user guide is copyrighted, include a copyright notice.
Place the copyright notice on the cover (and also the title page).
Disclaimer
Include a standard disclaimer inside the front cover that outlines the Terms and Conditions for using this guide.
Preface
Use this section to reference other documents related to the software. Make sure you refer to the correct release number for all software and documents that you refer to. If necessary, include a section on 'How to use this guide' as an introduction.
Contents
You must include a table of contents. the only exception is if your guide is less than ten pages, in which case you should probably refer to it as a Getting Started guide or Reference Guide.
If this user guide is more than twenty pages, include an index at the end of the document.
Body of the guide
This is the heart of the guide. In the main body, separate the procedures (also called instructions) from reference materials. This will help the user navigate their way through the guide much faster.
Procedures
Procedures help the user perform specific tasks. They are also known as instructions or tasks. Examples of these may include:
When, why, and how you can perform a task, for example, printing a document, cropping an image, uploading a file.
What the screen will show after you perform a task, for example, an updated view of your bank balance.
Examples of tasks and program operation.
Writing procedures
Writing procedures involves the following tasks:
Identifying the major tasks
Separating each major task into subtasks
Writing a series of steps that walk the user through each subtask
Using an 'if-then' approach when explaining decisions that users can make.
Chunking text
Breaking large pieces of information into smaller piece of information is called 'chunking.'
When writing user guides, you can separate information by menu options and their respective consequences, for example, showing the user the results of each action.
Subtasks that need to be performed can be divided into chunks. Each chunk can form a new chapter or section within the guide.
Use a consistent format for each section, for instance:
Introduce each section with an overview of the task to be performed
Describe the inputs and outputs. In other words, what the user must enter into the system and what the system will do as a result.
Describe the procedures for accomplishing these tasks.
Number your steps
When writing procedures, number each step and use the imperative form of verbs, for example:
Press ENTER
or
Click 'Yes' and press ENTER to submit your details.
Using the If-Then Approach
When users are allowed to make decisions, use an If-Then approach to show the different result for each decision they make.
If you choose 'Yes,' the program will make Firefox your default web browser. If you choose 'No,' it will set Opera as your default browser.
Use diagrams to illustrate more complicated procedures.
Reference Materials
User turn to reference material when they need detailed information on a specific topic, for example, settings or parameters they must enter.
Reference materials can include:
Program options, for example, different menus and buttons that are presented to the user
Keyboard options, for example, hold AltGr and 4 to show the Euro symbol
Error messages that may arise when you use the application
Troubleshooting tips to resolve these issues
Frequently asked questions that the user may have about the software
Back Matter
Add a Glossary of Terms and an Index towards the end of the document.
Glossary
The glossary should cover all acronyms and industry terms used in the document. Help the user understand your material. Do not alienate them by using jargon and assuming that they know the meaning on these words.
A short glossary can appear at the front before the table of contents
A larger glossary should appear in the back matter.
Highlight glossary terms (by italics, for instance) the first time they appear in text.
Index
Any guide longer than 20 pages benefits from an index. An index helps users locate specific items very fast without having to search through the entire document manually. Large documents without an index are impossible to use efficiently.
Establishing Standards
As well as writing the guide, you also need to consider how the document will be delivered, for example, as a book, online or a PDF.
Areas that need consideration include:
Format (the design and layout of the pages)
Style (elements affecting readability, such as font, size, color)
Other requirements that are specific to each delivery format. For example, PDFs may need security settings applied so material cannot be copied; partner logos may need to be added; terms and conditions may need to be updated.
Document Format and Structure
If you are writing a user guide for a client, rather then your own company, check if they use a specific style guide or have a preference for how the document should be presented. Check this with the client during the planning phase.
Use a document map to organize the guide. To do this:
Use headings for organizing information.
Include page numbers and section titles on every page, either in footers or headers.
Consider using dual columns. This lets you put headings in the left-hand column and the text in the right-hand column.
Style
Use an appropriate style. Decide on the technical level of your language, how you address the user, and conventions that are required.
Technical Language
Match the level of technical language with the audience ¯s level of proficiency. Always underestimate the knowledge of your readers rather than overestimate it.
Limit technical terms to those the user will encounter. If you must define a large number of terms, use a glossary to supplement definitions in the text.
Addressing the User
When writing procedures, use the active voice (e.g. Click this) and address users directly (write 'you' rather than 'the user').
When explaining an action, use the 'command' form of the verb:
'Choose an option from the menu and press [ENTER].'
Presenting your material
You can improve the readability of your documents by using specific formats to distinguish different types of information.
For example, you can distinguish the user's input from the system's response by:
Indenting text
Using columns to layout text
Providing illustrations or photographs that highlight key areas
Using different fonts and type features (bold, italics and underline)
Nonverbal devices, such as icons or diagrams, help supplement verbal instructions.
Special Requirements
If the guide is to be used outdoors, in a car, or on the move, make sure the font size is large enough to read easily.
Use spiral biding so the book does not to break easily, and high-quality paper so the text does not smudge or leave stains on the reader's hands.
PS - Download the User Guide Templates here
Living Section
Ask Tog, November, 1998
You may be a writer; you may be looking for a writer. Either way, you will find what you need in:
How to Publish a Great User Manual
Writing An Instruction Manual
Links in this article:
Jump to Guidelines Summary Response
When was the last time you curled up in bed with a really good user-manual just for the sheer joy of reading it? Never? Think that is some immutable law of nature, like the one that dictates all textbooks must be dull as dirt? 'Tain't so, McGee. Conflict Catcher is a must-have utility for anyone doing serious work on the Macintosh. It makes visible and helps troubleshoot the myriad mysterious add-ons that clutter the Mac OS. It has the perfect profile for being shipped with a manual that is both dull and unintelligible, but, apparently, someone screwed up, because it is shipping with one of the most witty, delightful, and lucid manuals I've ever come across. Good enough to read just for the sheer pleasure. Why? Because its author, David Pogue, is a gifted writer—always an advantage—and because he has followed the principles of manual design that ensure success. Steps to overcoming RTFM Software manuals tend to come in two flavors—dull and unintelligible. This has led directly and inexorably to RTFM!, the rallying cry of technical support people everywhere. Yet twenty years of yelling at callers to Read The Freaking Manual (or words to that effect) hasn't helped. Fixing the manual does. Follow these five easy steps, and your company will start saving big-time on the cost of customer support. 1) Supply a (real) manual. An amazing number of companies rationalize their way out of supplying a manual at all, then complain as loudly as anyone else about the stupid users calling customer support. A manual, since many people apparently don't know, is made of ground-up dead tree. Those delightful little PDF files that people insist on including on their CD ROM don't make it. First, my experience has been that Acrobat only opens around 40% of the time. (The rest of the time either it is distressed because it can't find some infinitely important font it wants or I've already got as many windows open as the OS can handle.) Second, even when it does open, these electronic manuals are not only difficult to read, they are anything but portable. (My 20' monitor is way to heavy to crawl into bed with, and I hate trying to read 400 page print-outs.) Besides, I just spent $395 for this software, and all you gave me was an 89-cent piece of plastic? Get real! A dead-tree manual necessary to the use of the program is the ultimate piracy-defeater. Pirates will blissfully copy your CD-ROM, they will blissfully upload your code to the newsgroups, but they won't Xerox the manual. It's not that they can't; they just won't. If you scrimp on the manual, you may still retain market share, but you won't be selling a lot of software. Some folks have found a clever way to drive people to piracy even while supplying a dead-tree manual. We now have the spectacle of major software houses, including Microsoft and Apple, turning out atrocious manuals in the full expectation that users will buy 'real' manuals in the bookstore, so the users can actually figure out how to use the program. These manufacturer's junk manuals typically display the characteristics of an edited feature spec, with no thought as to structure. (Sometimes the features are just listed in alphabetical order!) What a great technique for inspiring piracy: Anger users with a stupid, useless, paper manual they may spend days failing to understand, then force them spend lots of additional money buying a lucid, third-party manual. These people's advice to others? 'Steal the software and spend your money instead on this really great manual I found down at the bookstore.' Conflict Catcher 8 comes with two manuals—one where you learn about the program and one other really skinny one you use when your system has gotten in trouble and you are using Conflict Catcher to help straighten it out. Both are complete, both are lucid, both are all you will ever need to use the program, and both are essential. 2) Explain the problem being solved A lot of bad manuals out there are actually good feature specs that companies have just translated from engineeringese into a human language, then shipped. The problem with this approach is that you end up with a manual that explains every feature in depth, while keeping secret why anyone would ever want to use them. Programming language manuals are almost universal in this failing. They present 100 or 200 different commands without once mentioning what they are useful for. The human mind doesn't work from disembodied specs. Humans find it extremely difficult to store free-floating information. Explain a problem and offer a solution and people will remember it forever. Jump right to the solution, without ever presenting the problem, and it just won't penetrate. Let's examine this shortened excerpt from David Pogue's Conflict Catcher 8 manual on the subject of building a new system folder:
One of the most important troubleshooting tools is the clean system install—which means giving your Macintosh a brand-new system folder, straight off your Mac's original CD….Your new system folder is guaranteed to be free [of] corruption. Unfortunately, it's also guaranteed to be free of any useful enhancements….Before Conflict Catcher 8, the final step in the clean system install process was the tedious business of comparing, side-by-side, the contents of your old system folder with the contents of your new one….Only after you had performed this time-consuming comparison would your Mac be ready to go….Fortunately, Conflict Catcher 8 greatly simplifies and accelerates this…process.
By the time the user has finished reading the original five paragraphs from which this is drawn, they understand why they would want to do a clean install in the first place, what problem arises because of a clean install, and what Conflict Catcher 8 is prepared to do about it. David goes one step beyond, however, by 'selling' the product. That might seem silly, since obviously the person has already bought the product. However, when the reader understands that Conflict Catcher is going to eliminate for them a task that traditionally took three to four hours of the most boring, tedious work imaginable, they are going to get excited. Excited enough to tell their friends about Conflict Catcher. Excited enough even to write an article about it. Users now understand the motivation for the feature, as well of the value of the feature. Their minds have become fertile ground for the explanation of how to use the feature. A single reading will now transfer better than five readings would have in the absence of this understanding. 3) Present the concepts, not just the features. Well-designed software should be centered on a few, large concepts. HyperCard, Bill Atkinson's hypertext forerunner to the browser, had a single, underlying concept. Get that, and you got HyperCard. Miss it, and you were lost. The concept centered on layering, with both the background object, the 'card,' and objects place on the card each having several specialized layers. The HyperCard manual began with an exploded diagram of the layers. That single illustration meant the difference between the user quickly grasping the application and the user floundering around for days and days, trying to build up that same concept from bits and pieces of information scattered about the application and manual. Any time you learn a new piece of software, you go through the process of constructing a mental model of the software, what Don Norman calls the 'User Model.' Building a model requires a framework, and the framework consists of these large, key concepts. Without a framework, it is extremely difficult to learn. The designers gradually work toward these concepts as they experiment with the program. Because of this, they have often internalized the concepts so thoroughly that they may not even be consciously aware of them. That's why manuals written from specs are usually impossible to learn from. The key concepts are entirely absent, so the user has nothing upon which to hang the bits and pieces of knowledge offered. Instead, they kind of float around in a cloud until the poor reader finally sees the pattern. When a user does finally 'get it,' the bits and pieces do not then suddenly coalesce; that's not the way our memory works. Most of the bits and pieces, with nothing to hang themselves on, will have drifted off forever. The user must now re-read the entire manual, finally tying the bits and pieces in place on their new-found framework. Manual writers will not themselves 'get it' when they first start hammering on a new application. And I've even read manuals where the writer never did get it, either through lack of trying, lack of interest, or serious lack of ability. These manuals are useless. Manual writers must be introspective. They must be aware as the 'aha!' experiences that signal an incoming concept. They must then write that concept down and present it early enough to their readers that the readers don't have to go through the same struggle. That is the very essence of manual writing. The job becomes doubly difficult when you have already internalized the concepts, either because you are a member of the development team or are already thoroughly familiar with the application. That is another reason I was so impressed with Pogue's Conflict Catcher 8 manual, because I happen to know David entered the project with way too much foreknowledge to experience any 'aha's at all. It requires a consummate writer to be able to distill and present the key concepts under such conditions. 4) Give 'em more than they deserve Manuals need to cover the task domain, not just the operation of the program. That doesn't mean that a tax planner manual needs to cover the entirety of tax law. The depth and extent of the task domain that must be presented will depend on a number of factors, including the expected domain knowledge of the users and the amount of knowledge necessary for people to be able to use the application. Expected knowledge of users Writers (and marketers) tend to underestimate this. One of the great miracles of personal computers is that they offer a path for people to increase their knowledge and skill on their own. Extremely complex 'professional' applications, such as Adobe Photoshop, have millions of users who never set foot in a design class. They have learned from their peers, they have learned on their own, and they have learned from reading the excellent Photoshop manuals. Write a manual that excludes everyone but existing experts and you will seriously impact your volume of sales. Amount of domain knowledge necessary to use the application Conflict Catcher is a fairly simple application designed to act upon and maintain the most complex and invisible part of the Macintosh OS. The folks at Casady & Greene realized this early-on and have always offered a pair of products, boxed together, to deal with it. One of those products is the Conflict Catcher application. The other is the manual. Each is a valuable and vital tool for the Macintosh user. Together they are even better. Perhaps 75% of the Conflict Catcher manual is devoted to an in-depth explanation of how Macintosh extensions work. True, it would be difficult for the user to apply Conflict Catcher in the absence of such knowledge, but I've seen a lot of companies, faced with a similarly obvious need, completely ignore it. The depth and extent of this domain knowledge presented in Conflict Catcher is impressive. Conflict Catcher users, having absorbed this manual, are fully able to maintain and repair their system extensions without the Conflict Catcher application at all! It is just slower and more tedious. 5) Make it enjoyable to read One key concept, centered on what Macintosh extensions are and why they cause trouble, underlies all of Conflict Catcher. Let's see how two different writers present it: From the Conflict Catcher 4 manual:
Since you first began using your Macintosh, you've probably extended the services that it provides on more than one occasion to keep pace with your changing needs….All these seemingly unrelated changes have one important thing in common—the addition of specialized files to your system to make new services available….This growth has created…the need to be able to troubleshoot problems they can cause by interacting with one another or other parts of the system.
This is clear and competent, but consider David Pogue's introduction, in the Conflict Catcher 8 manual, of the same concept:
'Your Mac's software is the result of an accidental collaboration among hundreds of programmers.'
Now, that's great writing. In Conflict Catcher, the process of discovering a bad extension is a collaboration between the application and the user, with the application carrying out a series of experiments and the user reporting the results. In version 4, the manual carried this warning:
'It's extremely important to answer this question accurately, so, if there's any doubt in your mind, repeat the test and double check—it does't take much extra time and it ensures that the results of your test will be accurate.
David Pogue's handling:
'If, when Conflict Catcher asks you whether or not the problem is still around, you deliberately lie, then you deserve what you get. But, if you answered the question incorrectly by accident, keep in mind you can 'rewind' the conflict test without having to start over. Just….'
Both give you the information you need. David's is bedtime reading. The earlier manual is not. Guidelines Summary For the perfect manual, follow one of these two procedures: A) If you are a writer, write your manual using the following methodology:
1) Supply a (real) manual. 2) Explain the problem being solved 3) Present the concepts, not just the features. 4) Give 'em more than they deserve 5) Make it enjoyable to read B) If you need to hire a writer, hire David Pogue
A few substitutes do exist. Look through the supplemental manuals for sale in the book stores. Find out who among the authors can write. Contact them and offer them immense sums of money. It will be a good investment. If you are hiring full-time writers, ask for samples of their non-technical writing, as well as their technical writing. It has been my experience that real writers write because they are compelled to, not because they are being paid. Most technical writers who have never otherwise written cannot otherwise write. (I'm sure exceptions exist.) Actually read what they supply in the way of technical writing samples. Can you understand it? If not, why not? Is it because it is covering an area so complex and so arcane that you, a mere mortal, could not be expected to understand it? Or is it because the writer just regurgitated specs, instead of exposing the concepts and taking on the tough job of really training the users? Superb writers are out there. They can be found. There are no excuses.
Response
Here are some points I would add to yours: Writing is about Thinking The real story behind powerful writing is not the choice of words, but the formation of thoughts. This is the difference between David Pogue1s elegant prose and what went before. We may call it great writing. It is in fact great thinking. To achieve any trajectory, words must reflect value-added thought. The Manual as a First Date You can show up dishevelled and decline to respond to polite questioning (like FrameMaker1s on-line help). And there will be people who still persist in the search for your inner beauty. But it is not the way to bet. Once upon a time, Microsoft put considerable effort into its making its manuals a source of competitive advantage. It still shows, though less than before. There may be a message here. Manuals Can Sell Products The classic case in my view is Hewlett Packard1s 12C calculator in the finance industry. The 12C was a superb product, but it had a problem: nothing is less intuitive than RPN logic. The 12C's power was accessible solely through its manuals, and these were superb. They were tutorials worthy of the name—lucid, courteous, but never lightweight. Great instructional material. Which brings me to my next point. Technical Writers are Not in the Technical Business Technical writers are in the education business. There is more than something for them to learn from other educational material, especially in how complexity is unravelled. Of course, a technical writer has to know a bit from a byte, and a lot more. The most common misconception is that technical writing is a descriptive, mechanical process. In reality the core function is to teach. Kind regards, Barry Martyn
Excellent points all. I had left out the dimension of writer-as-teacher, and it is an important one.
Additional Responses
Writing A How To Manual
I agree entirely with your general assessment of user manuals in How to Publish a Great User Manual. However, I disagree with your recommendations for finding good technical writers on the following points: TOG: 'Look through the supplemental manuals for sale in the book stores. Find out who among the authors can write.' ME: Years of experience and lots of money wasted on commercially produced books have shown me that most of them perform very poorly. A truly useful, well-written software book is rare, even from authors who are highly recognized in the press. TOG: 'It has been my experience that real writers write because they are compelled to, not because they are being paid. Most technical writers who have never otherwise written cannot otherwise write. (I'm sure exceptions exist.)' ME: Technical communication is not primarily about writing. It's about teaching and communication. It's not about telling a story or expressing your thoughts or feelings. Organization, layout, simplifying complex concepts, explaining why and how to do things, and identifying with users on their own terms are much more important than finesse with language. Knowledge of the English language is no more a primary indicator of a good tech writer than knowledge of C++ statements and syntax are primary indicators of a good programmer. Of course knowledge of the fundamentals is required, but applying the fundamentals to produce a usable work is an entirely different matter in both professions. I've been in the business of technical communication for more than 24 years. I've won awards from peers and acclaim from users. I've hired writers and managed their work. One thing I can assure you is that people who think of themselves primarily as writers and who write literary or even marketing types of works usually are very poor at developing usable user guides. I've grown many gray hairs trying to work with 'writers' who can't understand the tasks users are trying to perform, who can't understand the technicalities of the software tools they are writing about, and who can't explain or teach concepts and procedures to others. But they can write beautiful poetry, short stories, and essays! (I'll guarantee you that the samples of poor writing you provide in your article were written by English-major, literary types of people.) The best technical communicator is a techy person who has the rare ability to communicate and teach through indirect means such as paper and online media.
Tom
The O'Reilly book on Frontier, by Matt Neuberg, is as close as I've ever come to a book on computers which could be could be considered literature. Luke Tymowski
I was quite impressed with your article, 'How to Publish a Great User Manual'. It was refreshing to read; I almost wanted to put on some jammies and cuddle up in bed with it. ;) *just kidding* Anyway, this is the first time I've ever seen the 'ASK TOG' web site. I have already bookmarked it. As a technical writer for a software company, I salute you and thank you for providing such a great web site. Keep up the good work! - Tommy
I enjoyed your article about David Pogue's Conflict Catcher 8 manual. I used to edit Pogue's work for IDG Books; I agree, the man's a natural. jim grey
As a longtime Windows WinHelp developer, I agree with you 100% on your observations in How to Publish a Great User Manual. I am a connoisseur of fine manuals and online help. Extensis Corporation, makers of the finest Photoshop plugin filters, produces consistently fantastic manuals. I rely on their PDF manuals because I typically buy software for immediate download from the Net. Have never experienced a moment of trouble with Extensis PDF manuals. Their hardcopy manuals are also excellent. Although not a vendor's manual, I found the IDG book TEACH YOURSELF ACCESS 97 VISUALLY to be the most stunning and superbly simple product guide I've ever seen. Check out ISBN 0-7065-6026-3. It is a visual delight which clearly delineates topics into understandable components. I purchased my copy at Borders booksellers and don't regret a dime of the expenditure. I only wish Microsoft had included the guide in my Access 97 application package. Take care. Roy Anderson
I found your article, 'How to Publish a Great User Manual,' to be a bit naive and amusing in its simplification of a profession. As a broadly and variously experienced technical writer familiar with not only the profession, but also the history of and research in the area of technical writing, please understand that:
until recently (a decade or so), engineers well-versed in their vocations—but not in English composition, spelling, and writing—wrote America's technical manuals
technical writers and technical writing are gradually gaining worldwide recognition as a profession
many universities now mandate communication courses for their engineering students
many universities now offer technical-writing specializations through their English departments
Americans tend to buy a product, rip it from the box, plug it in, and turn it on. We do not read the manuals, regardless of who the author is
other cultures, such as the Japanese, tend to buy a product, open the box, remove and read the manual, remove the product from the box per the instructions, and install and operate the product per the instructions. Note 'read the manual' in that previous sentence.
I offer no apologies, explanations, or excuses for American attitudes toward technical documentation. I'm inclined to resort to hasty (albeit likely accurate) generalizations about how our culture is, for the most part, intellectually lazy, impatient, and mired in a slovenly desire for both entertainment and instant gratification. I strongly suspect that an American appropriately coined the phrase, 'If all else fails, read the manual.' To pontificate, 'If you are a writer, write your manual using the following methodology' is both arrogant and ignorant. Conversely, if you, Tog, are a technical writer, feel free to argue the merits of tech-writing methodology; otherwise, either do your research or state your opinions as being just that. Consider that effective technical writing is an art unto itself, an art based upon grammar, style, consistent terminology, clarity, concision, factual accuracy, information mapping, layout and design (including fonts, indents, point sizes, illustration specifications and locations, table designs, and more), sentence length, translation concerns (increasingly important in this age of the Global Economy, European Community, and ISO 9001), documentation- and illustration-software selections, usability testing, spell checking, editing, proofreading, subject-matter-expert reviews, document validation (testing the manual against the actual product), indexing, resource scheduling and deadlines relative to product-release dates, print-vendor details, and myriad other facets. Clearly, technical writing is not five simple concerns, as you would lead your readers to believe. The world is full of lousy writing from would-be writers. Bad writing, in all forms, results in little more than wasted words, wasted time, wasted paper, and wasted money. In my humble opinion, those aspiring to write humor or fiction have no place in technical writing. Most of us in this profession believe that the reader's time is too valuable to waste with inane attempts at cute humor, wit, or lengthy, chatty exposition. Many tech writers prefer to define an audience and their expected knowledge base early on, then write to that audience. To suggest that your readers hire some guy based upon 'supplemental manuals for sale in the book stores' then 'offer them immense sums of money' is unsound advice. For example, not all software technical writers are effective hardware technical writers, and vice-versa; the installation and maintenance for the electrical and mechanical features of an automated bacon-processing line in a major food-product manufacturer is a world apart from the GUI for the same product. No one writer is all things to all people. I am a 'captive,' an in-house, full-time employee of a company that does not specialize in technical writing. I consider myself to be, and have been told time and again that I am, a highly effective technical writer. I am not a freelancer, as many tech writers are; these one-man shows are known in the industry as 'garage shops' in part because they lack the facilities (UNIX, Mac, and PC platforms running FrameMaker, Adobe Illustrator, Corel Draw, InterLeaf, Photoshop, etc., etc.) to meet the needs of a broad spectrum of clients. Previously, I worked in a technical-writing firm through which other companies contracted me to consult and write their manuals. Generally, these firms are a better, faster, and more efficient, reliable and frugal route than simply calling some guy who freelances or wrote a book . To suggest that 'real writers write because they are compelled to, not because they are being paid' is not entirely true. A journalist by degree, I fled the angry threats (from those whose names end up in unsavory stories) and low pay in part for the gentler, more lucrative vocation that is tech writing, and in part because I have a strong mechanical aptitude and a stronger knack for tech writing. I am not 'compelled' to write technical manuals; these documents are anything but compelling. Fiction, and inventing it, is compelling. Journalism, and writing news, is compelling. Technical writing is supposed to be dull in part because we do not tell a story; we simply and concisely describe how to complete tasks. Our audiences need fast information to achieve a means to an end. They do not expect to be entertained. They do not expect to find a plot or a happy ending. They expect accurate and concise information easily accessible through such simple tools as comprehensive indices, and intuitive information order and design. Our employers' budgets do not wish to pay to print any more pages of paper than are absolutely necessary. I hope I have instilled in you the complexities of a profession that is just now coming into its own as a respected profession. While I applaud your attempt at writing a 'how to' article, I pity you the verbal assaults you may likely endure from the very artisans of the skill you attempt to define. As a former journalist and a long-time tech writer, I strongly recommend, as Mark Twain once said, that you 'get your facts first, then distort them as you please.' Good luck, Mark Forseth
Writing A Good User Instruction Manual Guide Download
Strangely enough, this was the only verbal assault I received.
Don't miss the next action-packed column! Receive a brief notice when new columns are posted by sending a blank email to asktoglist-subscribe@yahoogroups.com.
Contact Us:Bruce Tognazzini Copyright Bruce Tognazzini. All Rights Reserved
