Search · Index

Guidelines in Documentation and Technical Writing

The Audience­

• Know your readers – who will benefit from the documentation you are writing
• Know their level of technical knowledge
• It may be best to assume that the reader does not have any idea about the topic, the system, or application you are writing about. In writing user guides, assume that the user has little computing knowledge. This way you will be able to write your documentation in simple terms.
• Address the readers or users directly. Use “you” instead of “the user”.
• If you are writing for more than one audience or reader, be sure to identify which one you are referring to especially when explaining a procedure or task.

Documentation Title

• The documentation title should be descriptive in such as way that the reader will have an idea what the document contains
• As much as possible, the titles should be short and written in phrases, not sentences.
• Font should be the same as the other sections of the documentation. This will establish uniformity in all your documentations. If you have started using the font Times New Roman, use it in the entire page as well as in other documentations.

Table of Contents

• It is a must to include a Table of Contents right after the Documentation title. This gives the reader an idea about the scope or topics the documentation will cover.
• The only exception for the use of a Table of Contents is when your documentation is less than 10 pages long.
• Use the same font as the Documentation title.
• If the documentation is too long, it may be helpful to create anchors to the sections so that the reader does not keep scrolling up and down to find the topics.  A single click on the topic from your Table of Contents will bring the reader to the desired section.

Terms and Definitions

• It is best to make a list of important terms that you will be using in your entire documentation. Be sure to include their definitions. This will help your reader understand better what you are referring to.
• Avoid highly technical terms or jargons. If this cannot be avoided, make sure to explain these technical terms in layman’s language.

Writing the body

• Use simple language with short sentences to help the reader or user understand better the application or system.
• Eliminate or avoid redundant words and phrases.
• It is advisable to use active rather than passive voice when constructing your sentences to avoid wordiness and emphasize the doer of the action. Otherwise, use passive voice if you want to emphasize the receiver of the action.
• Observe proper sentence structure:  Put verbs and familiar information at the beginnings of sentences, lists and new information at the ends.
• Be consistent in your format. If you write an overview for one section, at least, do the same for the other sections and subsections, if possible.
• When explaining about menus, menu options, buttons, etc, identify the items as they appear on the screen, or from left to right, top to bottom. This will give the reader or user an idea as to which direction you are going, or what item will be described next.
• Names of menus, menu options, dialog boxes, screens or windows, and other named items in the user interface should either be in bold or uppercase. For example, Click FILE and select OPEN.
• Use italics to indicate placeholders for information that the user should supply.
• File name extensions should be in lowercase.
• Acronyms, abbreviations, and key names should be in uppercase.
• When representing code samples, examples of screen text, or text that you would type at a command prompt, use monospace type.
• When indicating names of keys, key sequences and HTML element names, use capital letters. For example, Click DELETE to remove the file.
• Use a plus sign (+) to indicate simultaneous actions. For example, Press CTRL-S to save your document.
• Internet, Web, and email addresses should be in lowercase unless the address is case sensitive. For example, www.solutiongrove.com.
  
• Internet, World Wide Web and other shortened forms are treated as proper nouns and capitalized in all instances. For example, the Web, the Net.
• If you need to use information from other references, make sure you mention the source. If you use the exact words from these references, quote them.
• If the documentation is too long, it may be helpful to create anchors back to the Table of Contents to give the reader ease in going to and from the sections.

Procedures

• When writing a user guide, separate procedures or instructions from the main body to help the readers or users navigate through the system.
• Separate each step or task. Step-by-step procedure should be in numbered bullets
• Procedures should include when, where, why, and how to perform a task or a step.
• Procedures should also show the reader or user what will happen after a task is performed, what the screen will display, or what window will be opened.
• Separate the major tasks from subtasks.
• Use an if-then approach when explaining decisions that the readers or users should make.
• Explain the inputs and outputs. Describe the necessary inputs the user should make and the possible outputs the system or application will do as a result of the input.
• Mention about the pop ups and messages that prompt the user for a specific action and include the best or most ideal action to take.

Images and illustrations

• Use images or screen shots for illustration. This will guide the user especially when following procedures.
• Images should be in JPEG, GIF, or PNG format.
• Images or screen captures should be enough for the user to identify which screen or window you are illustrating, but not too big so as to force the reader to keep scrolling from left to write. This will also lessen the time needed for the images to be loaded on the page when the document is viewed on the Web.
• If the images appear quite blurred or too small for the user to see clearly, it may be helpful to give the user an option to view a larger image. Create a link that opens another window which displays the larger and, possibly, clearer image.
  

Common Spelling Errors

• online (not on-line)
• pop-up
• dial-up
• desktop
• CD-ROM (all uppercase)
• email (not e-mail)
• antivirus (not anti-virus)
• Web (capitalized)
• Web site (two words)
• Web-based
• information (not info)
• home page (two words)
• Mac OS X
• Internet
• on campus (noun) and on-campus (adjective)
• user name (two words)
• log in (verb) and login (adjective)
• catalog (not catalogue)
• course work (not coursework)
• database (not data base)
• in regard to (never in regards to)
• workplace (not work place)
• workstation (not work station)
• UNIX (not Unix)
• Use a.m. and p.m. and do not include o'clock. Designate noon or midnight, rather than 12 a.m. or 12 p.m.
• ensure means to guarantee; insure refers to insurance.
• screen saver (two words)

Helpful References:­

The University of North Carolina Greensboro
http://its.uncg.edu/Style_Guide/Technical_Writing/

McCormick Writing Standards Project
http://www2.writing.northwestern.edu/standards/standards.html

­Klariti
http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml