Please click here to help David McMurrey pay for web hosting:
Donate any small amount you can !
Online Technical Writing will remain free.
This page is under repair.
Technical documents (including handbooks, white papers and guides) have various designs depending on the industry, profession, or organization. This chapter shows you one traditional design. If you are taking a technical writing course, make sure the design presented in this chapter is acceptable. The same is true if you are writing a technical document in a science, business, or government context.
NotebookLLM-generated infographic of this chapter
Note: For years this online technical writing textbook generically referred to reports as practically anything containing technical information. But because "report" refers to a specific genre of technical document, the change had to be made to the generic "user guide," short for technical document.
user guides (generic name for technical documents) have specifications as do any other kind of project. Specifications for user guides involve layout, organization and content, format of headings and lists, the design of the graphics, and so on. The advantage of a required structure and format for user guides is that you or anyone else can expect them to be designed in a familiar way—you know what to look for and where to look for it. user guides are usually read in a hurry—people are in a hurry to get to the information they need, the key facts, the conclusions, and other essentials. A standard user guide format is like a familiar neighborhood.
When you analyze the design of a user guide, notice how repetitive some sections are. This duplication has to do with how people read user guides. They don't read user guides straight through: they may start with the executive summary, skip around, and probably not read every page. Your challenge is to design user guides so that these readers encounter your key facts and conclusions, no matter how much of the user guide they read or in what order they read it.
Be sure and see the example user guides.
The standard components of the typical technical report are discussed in this chapter. The following sections guide you through each of these components, pointing out the key features. As you read and use these guidelines, remember that these are guidelines, not commandments. Different companies, professions, and organizations have their own varied guidelines for user guides—you'll need to adapt your practice to those as well the ones presented here.
Transmittal Message
The transmittal message is either a cover letter (or memo) or an e-mail. The physical letter (or memo) is either attached to the outside of the user guide with a paper clip or bound within the user guide. The email contains a link to the user guide or the user guide attached. It is a communication from you—the user guide writer—to the recipient, the person who requested the user guide and who may even be paying you for your expert consultation. Essentially, it says "Okay, here's the user guide that we agreed I'd complete by such-and-such a date. Briefly, it contains this and that, but does not cover this or that. Let me know if it meets your needs." The transmittal message explains the context—the events that brought the user guide about. It contains information about the user guide that does not belong in the user guide.
Examples of a transmittal letter and transmittal message. Examples of a transmittal letter and transmittal message.
In the example of the transmittal letter, notice the standard business-letter format. If you write an internal user guide, use the memorandum format instead; in either case, the contents and organization are the same:First paragraph. Cites the name of the user guide, putting it in italics. It also mentions the date of the agreement to write the user guide.
Middle paragraph. Focuses on the purpose of the user guide and gives a brief overview of the user guide's contents.
Final paragraph. Encourages the reader to get in touch if there are questions, comments, or concerns. It closes with a gesture of good will, expressing hope that the reader finds the user guide satisfactory.
As with any other element in a user guide, you may have to modify the contents of this message (or memo) for specific situations. For example, you might want to add another paragraph, listing questions you'd like readers to consider as they review the user guide.
Front and back covers, title page
If your user guide is over ten pages, bind it in some way and create a label for the cover.
Front and Back Covers
Front cover (left) Back cover (right)
Title Page, Edition Notice, Copyrights, Trademarks
Preface
User Guide Main Chapters
Appendixes
Index
At its simplest, a user guide title is a copy of what's on the front cover—possibly with a few details added.
Edition Notice
Table of Contents
TOC
Whichever table of contents (TOC) format you use, these are the common standards:
- Starting page number only. Although some automatic TOC generators show the page range, standard is first page number only.
- Levels of headings to include. As shown in the TOC above, display the top two levels of headings unless the user guide has many subheadings. The TOC should provide an at-a-glance way of finding information quickly.
- Spacing and capitalization. Notice how the text items in the TOC above are indented. First-level headings use all caps; second-level headings use initial caps on each main word; third-level headings use sentence-style caps.
- Vertical spacing. Notice that the first-level sections have extra space above and below, which increases readability.
- All pages in the user guide (within but excluding the front and back covers) are numbered; but on some pages, the numbers are not displayed.
- In the contemporary design, all pages throughout the document use arabic numerals; in the traditional design, all pages before the introduction (first page of the body of the ) use lowercase roman numerals.
- On special pages, such as the title page and page one of the introduction, page numbers are not displayed.
- Page numbers can be placed in one of several areas on the page. Usually, the best and easiest choice is to place page numbers at the bottom center of the page (remember to hide them on special pages).
- If you place page numbers at the top of the page, you must hide them on chapter or section openers where a heading or title is at the top of the page.
- Does the user guide contain the following (properly formatted) in this order: transmittal message, front and back covers, title page; edition notice, table of contents; preface; chapters, appendixes (as needed); index, back cover.
- While it can be clever and playful, does the title of the user guide adequately indicate its subject matter? For details, see user guide titles.
- If the table of contents and list of figures (and table) use leader dots, are the page numbers right-aligned. If the table of contents and list of figures (and table) include page numbers on the right edge of the page, are leader dots used? For details, see TOCs and List of Figures (Tables).
- Does the introduction adequately indicate the topic, purpose, and intended audience of the user guide? Does it provide a list of subtopics to be covered and an indication of scope (what's not covered)? For details, see Introductions.
- Does this user guide contain adequate details, specifics, examples—whatever is needed to explain the assertions, the generalities?
- Considering the topic, purpose, and audience, are any vital contents missing from this user guide? Are any contents unnecessary? Is any information is this user guide technically incorrect? Is any critical technical information missing?
- In this user guide, does contain any obviously borrowed information that is not documented in any way?
- Do the citations (references to items in the information-sources list) occur in the body of the user guideformatted according to APA, MLA, or modified IEEE style? Are the items in the information sources list formatted according to APA, MLA, or modified IEEE style? For details, see Documentation: borrowed information sources.
- Do all tables and non-decorative figures include a descriptive title (caption) and source (if needed)? For details, see Table titles.
- Do all tables and non-decorative figures occur as near as posible to their relevant text?
- Do briefly explanatory cross-reference occur before the tables and non-decorative figures? For details, see Explanatory cross-references.
- Is a standard format of headings and subheadings used in the body of the user guide? For details, see Headings.
- Do main sections (chapters) of the user guide start a new page in print versions?
- Are numbered vertical lists used for list items in a required order? Are bulleted vertical lists used for list items in no required order? Are lead-ins use before all lists? For details, see Vertical lists.
- Are direct quotations attributed, and are the attributions correctly punctuated? Are all direct quotations, summaries, paraphrases properly cited according to APA, MLA, or modified IEEE style? For details, see Quotations & attributions.
- Is the text of the user guide free of grammar, usage, and punctuation errors? For details, see Common Grammar, Usage, Spelling Problems.
- Is the text of the user guide free of wordiness and other sentence style errors? For details, see Wordiness, other sentence-style problems.
- Can this user guide be understood by its target audience (as indicated in the transmittal message and introduction)? For details, see Audience analysis, and see Translating the Technical.
- AT, to complete your evaluation of my user guide, assign a numeric grade from 100 to 55).
Depending on your organization's requirements, you have two format choices for tables of contents (TOC):
This TOC uses decimal-numbering style for the chapter and section numbers, which is common in user guides. Others in this book use the uppercase roman-numeral style for the top-level chapters only (see ).
Trouble creating a nicely formatted TOC? See Create a professional-looking TOC
Commas and page numbers. If a leader-dot format is not required and you prefer to avoid it, you can use this commonly accepted format:
Simple TOC text with commas and page number.Preface
See this example of a preface:
.
If there are no tables, make it "List of Figures." In a technical writing course, ask your instructor if the decimal-numbering style for headings is required.
User Guide Main Chapters
The body of the user guide is of course the main text of the user guide, the sections between the introduction and conclusion. Illustrated below are sample pages.
Appendixes
Appendixes are those extra sections following the conclusion. What do you put in appendixes?—anything that does not comfortably fit in the main part of the user guide but cannot be left out of the user guide altogether. The appendix is commonly used for large tables of data, big chunks of sample code, fold-out maps, background that is too basic or too advanced for the body of the user guide, or large illustrations that just do not fit in the body of the . Anything that you feel is too large for the main part of the user guide or that you think would be distracting and interrupt the flow of the user guide is a good candidate for an appendix. Notice that each one is given a letter (A, B, C, and so on).
Index
Documenting your information sources is all about establishing, maintaining, and protecting your credibility in the profession. You must cite ("document") borrowed information regardless of the shape or form in which you present it. Whether you directly quote it, paraphrase it, or summarize it—it's still borrowed information. Whether it comes from a book, article, a diagram, a table, a web page, a product brochure, an expert whom you interview in person—it's still borrowed information.
Documentation systems vary according to professionals and fields. Engineers use the IEEE system, examples of which are shown throughout this chapter. Another commonly used documentation system is provided by the American Psychological Association (APA). See documentation for details.
Other User Guide Elements
Page Numbering
Page-numbering style used in traditional user guide design differs from contemporary user guide design primarily in the former's use of lowercase roman numerals in front matter (everything before the introduction).
Headings
In all but the shortest user guides (two pages or less), use headings to mark off the different topics and subtopics covered. Headings enable readers to skim your user guide and dip down at those points where you present information that they want. See headings for guidelines on headings.
Bulleted and Numbered Lists
In the body of a user guide, also use bulleted, numbered, and two-column lists where appropriate. Lists help by emphasizing key points, by making information easier to follow, and by breaking up solid walls of text. See lists for guidelines on lists.
Symbols, Numbers, and Abbreviations
Technical discussions ordinarily contain lots of symbols, numbers, and abbreviations. Remember that the rules for using numerals as opposed to words are different in the technical world. The old rule about writing out all numbers below 10 does not always apply in technical user guides. (See numbers vs words for guidelines.)
Except from the body of ???.
In a technical writing course, ask your instructor if the decimal-numbering style for headings is required. Also, a different documentation system may be required—not the IEEE, which is for engineers.
Graphics and Figure Titles
In technical documents, you're likely to need drawings, diagrams, tables, and charts. These not only convey certain kinds of information more efficiently but also give your user guide an added look of professionalism and authority. If you've never put these kinds of graphics into a , there are some relatively easy ways to do so—you don't need to be a professional graphic artist. For strategies for adding graphics to s, see graphics. For strategies for adding tables to s, see tables.
Cross-References
You may need to point readers to closely related information within your techdos, or to other information sources that have relevant information. These are called cross-references. For example, they can point readers from the discussion of a mechanism to an illustration of it. They can point readers to an appendix where background on a topic is given (background that just does not fit in the text). And they can point readers outside your user guide to other information—to articles, user guides, and books that contain information related to yours. When you create cross-references, follow these guidelines presented in cross-references.
Note: Longer user guides often use the page-numbering style known as folio-by-chapter or double-enumeration (for example, pages in Chapter 2 would be numbered 2-1, 2-2, 2-3, and so on). Similarly, tables and figures would use this numbering style. This style eases the process of adding and deleting pages.
AI Prompts for User Guides
Checklists, which typically go unread, can be used as source for AI prompts with some modification. Copy the following, paste it into an AI system such as Google's Gemini, and see what you may have missed.
Note: All references to the content, format, style of data reports or its components can be found at online techncial-writing textbook.
|
AI Prompts for User Guides |
Related Information
How to Write User Friendly Help Topics for Beginners. clickhelp.com
I would appreciate your thoughts, reactions, criticism regarding this chapter: your response—David McMurrey.
