# Fundamental Concepts of Technical Documentation

This chapter provides a brief introduction to writing technical documentation.

## General Style Requirements

Technical writing for computer applications imposes special constraints beyond the basic requirements of good prose. Good technical documentation has the following characteristics:

Comprehensive

- Describe all of the functionality of a product. Do not omit functionality that you regard as irrelevant for the user.

Conformant

- Describe what you see. Do not describe what you want to see. Present your information in the order that users experience the subject matter.

Clear

- Read The Elements of Style to help make your writing clear.

Consistent

- Use agreed vocabulary throughout your documentation. Use the same vocabulary as other writers who are working on related documentation.

Concise

- Review your work frequently as you write your document. Ask yourself which words you can take out. See fundamentals-2 for a specific guideline.

## Golden Rules

This section contains some basic style guidelines. Subsequent chapters of this book expand on these guidelines to give more detailed guidance.

Golden Rule 1 | Limit each sentence to less than 25 words. Limit each procedure step to 23 words.
Example | Under normal operating conditions, the kernel does not always immediately write file data to the disks, storing it in a memory buffer and then periodically writing to the disks to speed up operations.
Rewrite | Normally, the kernel stores the data in memory prior to periodically writing the data to the disk.

Golden Rule 2 | Limit each paragraph to one topic. Limit each sentence to one idea. Limit each procedure step to one action.
Example | The Workspace Switcher applet helps you navigate all of the virtual desktops available on your system. The X Window system, working in hand with a piece of software called a window manager, allows you to create more than one virtual desktop, known as workspaces, to organize your work, with different applications running in each workspace. The Workspace Switcher applet is a navigational tool to get around the various workspaces, providing a miniature road map in the GNOME panel showing all your workspaces and allowing you to switch easily between them.
Rewrite | You can use the Workspace Switcher to add new workspaces to the GNOME Desktop. You can run different applications in each workspace. The Workspace Switcher applet provides a miniature map that shows all of your workspaces. You can use the Workspace Switcher applet to switch between workspaces.
Tip | Plan the order of paragraphs before you start writing. Decide which topic you want to cover in each paragraph.

Golden Rule 3 | Use explicit examples to demonstrate how an application works. Provide instructions rather than descriptions.
Example | There is a text box that you can use to find out the definition of a word.
Rewrite | To request a definition of a word, type the word in the text box, then click on the Lookup button.
Tip | Do not apply this guideline too rigidly. Sometimes you must explain how software works to support your how-to examples.

Golden Rule 4 | Write in a neutral tone.
Example | The applet is a handy little screen grabber.
Rewrite | You use the applet to take screenshots.

## Tone

Inappropriate tone can hinder reader access to information. A neutral tone free of opinion or personal flavor reduces the processing load for the reader to understand the information. Another benefit of a neutral tone is that several writers can work in parallel on a large technical documentation project. Furthermore, different writers can join the project at different times. The use of a neutral tone helps to achieve consistency across a documentation set, and thereby facilitates user access to information. The best way to achieve a common, neutral tone is to apply the following principles:

Avoid humor

- Humor distracts from the information you are trying to provide. Humor also makes documentation difficult to translate. Stay factual.

Avoid personal opinions

- Whether you think a function is useful or woeful is irrelevant. Report the function to the user, with instructions about how to use the function. Stay accurate.

Avoid colloquial language

- Colloquial language is difficult to translate and usually culture-specific. Stay neutral.

Avoid topical expressions

- An expression that is in common use today might convey something completely different tomorrow. Stay technical.

Avoid aspirational statements

- Statements about the future developments of a product do not belong in technical documentation. Write about what you see right now. Stay real.

## Reaching the Right Audience

All of the decisions that you make about the structure and content of a manual follow from an understanding of the audience. You need to think about how the audience accesses the documentation, what sort of information the audience needs, and the experience level of the audience. Usually, you need to create documentation that is suitable for different audiences. The following sections introduce some of the audience-related topics you need to consider.

### User Motivation

Do not waste the time of the user who looks for information in your documentation. Users do not read technical documentation for entertainment. Users usually have specific questions. You need to give clear answers to those questions.

### New Users

New users to the GNOME Desktop are likely to consult online Help for guidance about unfamiliar applications or functionality. Each Help manual should contain enough introductory information to tell new users how to start using the application. Each Help manual should also contain enough usage instructions to tell users the different actions that they can perform with the application. Keep these instructions task-oriented. You do not need to describe GUI screens, dialogs, and dialog elements in Help, unless there is an unusual feature that affects your instructions.

### Experienced Users

Experienced users are more likely to use documentation as a reference. The documentation therefore needs to be complete, well-organized, and in the case of printed manuals, well-indexed.

### Do Not Offend Your Audience

To avoid offending your readers, apply the following guidelines to your documentation:

Avoid insider language

- Insider language includes both undefined jargon and the tendency of the computer community to shorten words. For example, use the term documentation instead of the term docs. You can identify jargon if terminology fails the following conditions:

  - A term does not appear in wordlist, in this guide.

  - A term does not appear in the American Heritage Dictionary.

  - A term does not appear in the glossary of the manual that you are writing.

  - A term is not defined in the body text of the manual that you are writing.

Avoid sexist language

- Pronoun constructions such as his/her or s/he do not exist. There is no need to identify gender in your instructions.

Avoid culture-specific language

- There is little point in giving an example that everyone in your town knows about, but is a complete mystery to everyone else in the world.

Avoid talking down to your reader

- There are few experiences more irritating for a user than documentation that says an action is easy or quick, when in fact the user cannot complete the action. Do not qualify or prejudge actions.

Other parts of this guide discuss in more detail tone and language usage that can cause offense.

## Structure

Good organization goes a long way towards creating good documentation. You need to consider the type of manual that you want to create before you start work. Not every manual can follow the same structure. You must break up a complex, multifunction application such as Evolution into many parts, to provide detailed explanations of the separate functional modules. An applet, on the other hand, needs a brief description of the GUI, basic usage instructions, and details on any necessary preferences.

### Help Manuals

Wherever possible, use templates to ensure that your Help manual follows a standard approach. You can find templates for Help manuals in the GNOME Handbook of Writing Software Documentation.

### Guides

If you need to write a guide about a large application or a set of applications, then the book is substantially longer than a Help manual. You need to develop an outline plan for your guide. The precise composition of your manual depends on the subject, however in general you need the following book components:

Front matter

- Defines the function of the book. Includes navigation aids to the remaining sections of the book, such as a table of contents, or links. This section might contain a Preface.

Introduction

- Explains the application to new users. You should provide an expanded definition of the function of the application, built around illustrations and examples.

Document body

- Consists of several sections or chapters that provide a more detailed explanation of how to use the application. This is where you achieve completeness, telling the user how to complete all the main tasks associated with the application. Chapter headings are usually descriptive of the each topic area. Sub-headings within the chapter are usually task-oriented, so that users can quickly find information about a specific action within the topic area.

Glossary

- Defines specific terms in the book. You do not need to define terms that are in the American Heritage Dictionary.

Appendices

- Contain additional notes about related topics that are not directly explained in the document body.

Index

- Provides keyword links to specific concepts in the book. Follow the guidelines in this guide to create an effective index.