![[Note]](./stylesheet-images/note.png) | Bibliographic Information |
|---|---|
This section is drawn primarily from the GDSG. |
This chapter provides a brief introduction to writing technical documentation.
Technical writing for the Fedora Project imposes special constraints beyond the basic requirements of good prose. Good Fedora 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.
- Conforming
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 (http://www.bartleby.com/141/) 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. Refer to Section 8.2.2, “Golden Rules” for specific guidelines.
This section contains some basic style guidelines. Subsequent sections in this chapter expand on these guidelines to give more detailed guidance.
- Golden Rule 1: Be brief
Limit each sentence to fewer than 25 words.
Limit each procedure step to 23 words.
- Golden Rule 2: Be organized
Limit each paragraph to one topic.
Limit each sentence to one idea.
Limit each procedure step to one action.
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.
Example 8.5. Incorrect: Disorganized topics
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.
Example 8.6. Correct: Organized topics
![[Tip]](./stylesheet-images/tip.png)
Tip Plan the order of paragraphs before you start writing. Decide which topic you want to cover in each paragraph.
- Golden Rule 3: Be demonstrative
Use explicit examples to demonstrate how an application works. Provide instructions rather than descriptions.
There is a text box that you can use to find out the definition of a word.
Example 8.7. Incorrect: Describes but does not demonstrate
To request a definition of a word, type the word in the text box, then select Lookup.
Example 8.8. Correct: Demonstrates usage
Tip Do not apply this guideline too rigidly. Sometimes you must explain how software works to support your how-to examples.
- Golden Rule 4: Be objective
Write in a neutral tone.
Inappropriate tone hinders reader access to information. A neutral tone free of opinion or personal flavor improves the reader's comprehension. Neutral tone helps writers to work in parallel on a large technical documentation project. Furthermore, additional writers may join the project at any time. 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.
All of the decisions that you make about the structure and content of a manual follow from an understanding of the audience. Consider 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.
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 to Fedora Core are likely to consult online tutorials for guidance about unfamiliar applications or functionality. Each tutorial should contain enough introductory information to tell new users how to start using the relevant functions. Each tutorial should also contain enough usage instructions to tell users the different actions that they can perform with the command or function. Keep these instructions task-oriented. Do not describe GUI screens, dialogs, and dialog elements in a tutorial, unless there is an unusual feature that affects your instructions.
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.
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
documentationinstead of the termdocs. A term may be jargon if it fails all the following conditions:The term does not appear in the Fedora Jargon Buster (http://fedora.redhat.com/docs/jargon-buster/).
The term does not appear in the American Heritage Dictionary (http://www.bartleby.com/61/ ).
The term does not appear in the glossary of the manual that you are writing.
The term is not defined in the body text of the manual that you are writing.
- Avoid gender-specific language
Pronoun constructions such as
his/herors/hedo 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.