%FEDORA-ENTITIES-EN; ]> Writing good technical documentation is not simply reproducing command lines and instruction sets. Good documentation is easy to read, understand, and translate, and presents a concise logical progression of concepts. Good documentation can also be defined by what it does not contain. Your tutorial should avoid: Excessive wordiness Unnecessary or undefined jargon Grammatical or spelling errors References to yourself or your experiences Remarks which might offend or confuse any reader This chapter contains style rules and guidelines for writing &FED; documentation. Guidelines are not the same as rules. It is acceptable to violate a guideline when it makes your material easier to understand. Follow guidelines whenever possible, but follow rules at all times. Assume any advice is a guideline unless identified otherwise.

Writing well comes naturally to almost no one. It is a skill that professional writers, even famous ones, must practice constantly. Style style is the quality that separates elegant writing from the merely functional. Elegance comes in many forms. In prose and poetry, elegant writing may not follow some (or any) common rules of grammar, syntax, or spelling. A good example is Episode 18, "Penelope," in James Joyce's novel Ulysses For example, refer to. http://www.online-literature.com/james_joyce/ulysses/18/. Please note that this example contains some mature themes and language, and is not suitable for all readers. . There, Joyce uses long streams of words without punctuation to simulate a character's internal consciousness. By violating basic rules of grammar and syntax, Joyce simulates the disorganized but loosely connected thought patterns of the narrator. Technical documentation, however, should always respect these rules. The more a document departs from standard language usage, the more difficult the material becomes for the reader. For example, readers may not be native speakers of the language used, or they might be reading a translation. If the writer uses slang, idioms, or jargon, a reader or translator may easily become confused. The following example compares two different written executions of the same idea: So you made the changes I showed you in the last section. What's the next thing you should do? Just pop your thumb drive onto your system and read the messages log. When you see "USB device found," then Bob's your uncle. After you complete the configuration changes above, attach the USB removable media to your system. Use the dmesg command to examine the kernel message log. The message USB device found indicates that your device was installed successfully. The first example is more conversational English, which is not appropriate for official written documentation. The second example is more formal, but as a result it is easier to comprehend, both for native readers and translators. Following style rules and guidelines also makes readers more comfortable with a set of documents. Consistent style enhances the professional appearance of documentation, and its perceived value. On the other hand, lapses in punctuation or poor grammar negatively affect a reader's reaction to written material. A reader can feel that an otherwise correct technical document is lacking in authority, simply because it is poorly written. Readers feel at ease when they do not have to struggle to understand an author's use of language. This chapter cannot possibly cover enough material to make every reader a good writer. Some manuals devoted entirely to writing style are themselves hundreds of pages long. This chapter provides enough guidelines for intermediate writers to understand style usage in technical documentation. If you are not a practiced writer, whether of technical documentation or otherwise, you may benefit from other style resources. The following list is far from comprehensive, but provides a starting point: The Elements of Style, by William Strunk. Basic rules and links to online versions can be found at: http://en.wikipedia.org/wiki/The_Elements_of_Style The Chicago Manual of Style, by the University of Chicago Press. Online version: http://www.chicagomanualofstyle.org/ Paradigm Online Writing Assistant, maintained by Chuck Guilford, Ph.D. Online only: http://www.powa.org/ There are many free software documentation projects which have developed their own style guidelines. This chapter, in fact, draws heavily on the GNOME Documentation Style Guidelines (GDSG). You may read the original GDSG at http://developer.gnome.org/documents/style-guide/.

This section is drawn primarily from the GDSG. This chapter provides a brief introduction to writing technical documentation.

Technical writing for the &FP; imposes special constraints beyond the basic requirements of good prose. Good &FED; 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://en.wikipedia.org/wiki/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. Refer to 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. 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. Normally, the kernel stores the data in memory prior to periodically writing the data to the disk. 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. 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. 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. To request a definition of a word, type the word in the text box, then select Lookup. 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. The applet is a handy little screen grabber. Use the applet to take screenshots.

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 &FC; 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 documentation instead of the term docs. A term may be jargon if it fails all the following conditions: The term does not appear in the &FED; 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/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.

This section is drawn partly from the GDSG, and partly from The Elements of Style, updated as necessary for the needs of 21st-century technical documentation writers. This section contains an alphabetical list of grammar and usage guidelines for use in &FED; documentation. Many of these guidelines are only applicable to English-language usage, refer to the American Heritage Dictionary (http://www.bartleby.com/61/) and the Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) Abbreviations A shortened form of a word or phrase that takes the place of the full word or phrase, such as Dr., a.m., p.m., and so on. Apply the following rules when you use abbreviations: Avoid creating new abbreviations. Unfamiliar abbreviations can confuse rather than clarify a concept. Do not explain or expand familiar abbreviations. Do not include familiar abbreviations in the glossary of your manual. For abbreviations of phrases, such as i.e. for "in other words" and e.g. for "for example", do not use the abbreviation. Spell out the entire phrase. Adjectives Use adjectives with caution. If an adjective is necessary to differentiate between items, then use adjectives. In all cases, test whether the phrase can stand alone without the adjective. Acronyms A term that represents a multi-word term. Typically, acronyms are formed in the following ways: From the first letters of each word in a compound term, for example Table of Contents (TOC). From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME). Apply the following rules when you use acronyms: On the first occurrence of an acronym, spell out the full term, with the acronym in parentheses. Do not spell out the full compound for well-known acronyms, unless you think the information is useful for readers. Avoid creating new acronyms. Unfamiliar acronyms can confuse rather than clarify a concept. Write the acronym in uppercase letters, unless there is a compelling case for lowercase. Include the acronym and the full term in the glossary of your manual. Adverbs Use adverbs with caution. If an adverb is necessary to qualify the function of a component, then use an adverb. In all cases, test whether the phrase can stand alone without the adverb. Classic superfluous adverbs simply, easily, quickly. Anthropomorphism Do not apply emotions, desires, or opinions to software applications. Do not apply a sense of location or dimension to a software application. A user can not be "in" a text editor. Articles Do not use the definite article the to begin any of the following items: Manual titles Chapter titles Headings Figure captions Table captions Callouts Apostrophe Do not use apostrophes except where absolutely required Do not use apostrophes to denote possession. Do not use apostrophes to denote contractions. Do not use apostrophes to denote plurals. the Main Menu's Help option don't use the default option several SCSI disk's the Help option on the Main Menu do not use the default option several SCSI disks Brackets Do not use brackets [such as these] as a substitute for parentheses (such as these). Use brackets for optional command line entries. Do not use angle brackets to indicate variables in text, instead use the replaceable tag. Refer to for information about using this tag. Capitalization Capitalize in the following situations: All letters in acronyms, unless the acronym is a well-known exception Initial letter of the first word in a list Initial letter of the first word in a callout Initial letter of a key name, such as the Shift key Initial letter of a sentence Avoid starting a sentence with a command name or application name that has a lowercase initial letter. Initial letter of a complete sentence after a colon Do not capitalize in the following situations: A compound term that is followed by an abbreviation or an acronym When you want to emphasize something Variable names The initial letter of an incomplete sentence after a colon Captions Use the same rules as for headings, for all captions accompanying figures and tables. Do not put a period at the end of a caption. Colon Use a colon in the following situations: To introduce a list Before an explanation After an introduction Do not use a colon in the following situations: To introduce a figure or a table To introduce headings At the end of an introduction to a procedure Column headings Use the same rules as for headings. Comma Use commas in the following situations: To separate items in a series To separate the parts of a sentence To separate nonrestrictive phrases Instead of dashes to set off appositives With for example and similar expressions Do not use commas in the following situations: In a series of adjectives used as one modifier Between two short independent clauses Commands Do not use commands as verbs. Contractions Do not use contractions such as can't, don't, or isn't. Dash Do not use the em dash or the en dash. Use a paragraph break or a colon instead, where you want to create an introductory piece of text. If you have several items that you want to introduce, then you can use a variable list. Ellipsis Use an ellipsis in the following situations: To show that you have omitted something from a sentence To indicate a pause when you quote displayed text Fractions Follow these rules when using fractions: Use numerals for fractions in tables and in units of measurement, but spell out fractions in prose. Use a space between a numeral and a related fraction, if there is a possible ambiguity. For example: 1 1/2 instead of 11/2. If a fraction is used in a compound modifier, insert a hyphen between the fraction and the unit of measurement. Gender Refer to . Grammar Use standard American English grammar rules, refer to the Chicago Manual of Style ( http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) Headings Use the following capitalization rules in headings: Initial uppercase letter of the first word Initial uppercase letter for all nouns, adjectives, and verbs. All lowercase letters for conjunctions, articles, and prepositions of fewer than four letters Initial uppercase letter for prepositions of four letters or longer Initial uppercase letter for conjunctions of four letters or longer Hyphen Use hyphens in the following situations: With a numeral in a compound modifier To prevent ambiguity With some standard prefixes and suffixes. Use the American Heritage Dictionary (http://www.bartleby.com/61/) for guidance In spelled-out fractions In variable names of two or more words, such as directory-name. Note: filename is an exception. Do not use hyphens in the following situations: For industry-accepted terms To construct verbs With an adverb ending in ly With numerals as single modifiers With a word that is listed as unhyphenated in the American Heritage Dictionary (http://www.bartleby.com/61/), and that uses a common prefix With trademarked terms Latin terms Do not use Latin terms. Use an equivalent English term instead. Like Do not use the term like to denote equivalence or similarity. Lists Introduce a list with a complete sentence that ends with a colon. Numbers Spell out numbers in the following situations: Numbers from zero through nine unless the number is part of a measurement Approximations Extreme values such as million, but precede the value with a numeral Any number that begins a sentence A number that is immediately followed by a numeral, for example: two 10 MB files Numerals Use numerals in the following situations: The number 10 or greater Negative numbers Most fractions Percentages Decimals Measurements Units of time smaller than one second References to bits and bytes Parentheses Use parentheses in the following situations: To contain the abbreviation of a term on the first occurrence of the full term In man page references, specifically the section number Period Use a period in the following situations: To end a sentence In file and directory names In abbreviations that can be mistaken for words, such as a.m. and U.S. Punctuation Use standard American English punctuation rules. In addition to the specific points of punctuation in this section, refer also to the Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) Punctuation in numbers Do not use a comma in numerals of four digits. Use a comma in numerals of more than four digits. Quotation marks Use quotation marks to indicate material that is taken verbatim from another source. Do not use quotation marks to excuse terms from legitimacy. If the term is not legitimate, then use another term. If you must use that term, declare the term in the glossary and make the term legitimate. See v. Refer to When referring a user to another resource, use "refer to" instead of "see", and "refer also to" instead of "see also". This differentiates from the see and seealso tags that are used in indexing. These tags create special links in the index. To be consistent throughout the document, we reserve the special words "see" and "see also" for hyperlinked index references, and use "refer to" and "refer also to" for non-hyperlinked and non-indexed references. Semicolon Do not use semicolons. Slash Except where required as part of a filename, do not use slashes "/" in your writing. The construction and/or, for example, does not exist. Use one or the other term instead. Spelling Use standard American English spelling rules, refer to the American Heritage Dictionary (http://www.bartleby.com/61/) for guidelines. Titles For manual titles use the same rules as for headings. Units Follow these rules when using units: Use standard abbreviations for units of measurements, do not invent your own abbreviations. For further guidelines, refer to the IEEE Standard Dictionary of Electrical and Electronics Terms. Use periods for abbreviated units that might be mistaken for a word. Most standard abbreviations of units account for both singular and plural usage. Insert a space between the numeral and the unit of measurement.

This section contains usage tips based on situations the &FDP; editors have encountered in the past. You should read and understand these examples to improve your own documentation. The &FDP; editors welcome additional examples.

Always use active voice, except when it is awkward to do so. The tutorial tells the user how to accomplish a task, and should give instructions clearly and concisely. Avoid using "must," "need to," and the like. These words are redundant in a tutorial, since the reader assumes you are outlining necessary steps to accomplish a task. Also avoid using "maybe," "might," and other words that indicate you are unsure about the subject matter. Your tutorial should cover a subject authoritatively. The reader should never be concerned about unknown effects of following the tutorial. The yum update command must be run. You might want to run the yum update command. Run the yum update command.

Write in the present tense. A good rule of thumb is that the words "will" and "shall" are almost never needed in describing what the user should do or see. They add unnecessary length to sentences and can confuse translators. They are also often indicators of passive voice; refer also to . The application will display a list of target files. A list of target files will be displayed by the application. The application displays a list of target files.

Do not use the first person "I," "we," or "us" to refer to yourself the writer (whether including the reader or not), the &FDP;, the &FED; community, or any other group. Do not refer to users with a third person pronoun ("he," "she," or "he or she") or the word "one." It is acceptable to refer to the reader with the second person pronoun "you." As described in the last section, I always run up2date before configuring the Samba server. If the user needs to back up his or her files, s/he should use the tar or cpio command. Refer to the section on up2date before configuring the Samba server. If necessary, users can back up files with the tar or cpio command.

Avoid negative words when possible, since they give documentation an overly dogmatic tone. The word "avoid" is useful for this purpose. Note that contractions are often used for negative words such as don't or can't. Refer to .

Avoid overuse of "typically," "usually," "most of," "many," and the like. While occasional use of these constructions is acceptable, overuse reduces the authority of your documentation. The documentation should adequately cover a stock installation of &FC;. It is impossible for a tutorial-length document to cover every possible configuration scenario. Address the most common scenarios and note discrepancies only as required.

Avoid covering redundant material, such as how to update a &FC; system. These overarching topics may be covered in other tutorials. Writers frequently violate this guideline because they feel their tutorial is not long enough. Keep your tutorial from wandering off-topic. Instead, refer the reader to a separate tutorial whenever possible for complete coverage of that topic.

Avoid statements such as "One of the most important things to do is XYZ." If the procedure is important, the reader already expects it to be in your tutorial. The converse is also true: If a procedure appears in your tutorial, the reader expects it is important. This is especially true if you use a whole section for the procedure in question. Merely state, "Do XYZ." Then elaborate as required. If the whole section concerns how to do XYZ, leave this sentence out entirely. Refer also to .

Use precise words for actions users should take. Do not instruct users to "go" to a selection, or "find" a menu. Go to the Main Menu -> Foobar Find the option labeled Search From the Main Menu, select Foobar Select the Search option If you are writing about a GUI-only application, you may use "click" freely. If you are writing about an application that has a text-mode interface, use "select" instead as shown above.

This section contains tips on how to use DocBook tags more effectively in your documentation.

Avoid overuse of admonitions. Keep admonitions short and effective by using only the most important material inside the admonition. Move any background material required to explain the admonition statements outside the admonition. Use a short but descriptive title for an admonition. Use title case for the admonition title. The sfdisk command accepts a script file as standard input to set up partitions on a hard disk. Sometimes sfdisk will simply reject an erroneous input file. In other cases, it will use the input verbatim, writing an incorrect partition table to your disk. Always use the sfdisk -n command to check your input file before writing to the disk. The sfdisk command accepts a script file as standard input to set up partitions on a hard disk. Sometimes sfdisk will simply reject an erroneous input file. In other cases, it will use the input verbatim, writing an incorrect partition table to your disk. Always use the sfdisk -n command to check your input file before writing to the disk. Avoid punctuation in titles for sections or admonitions, except for commas only where demanded. Use a title that says something about the admonition comment, such as "Reboot Required," instead of simply using the admonition type for a title ("Note"). Follow the capitalization rules for headings in the title of an admonition.

If your documentation formally states a specific value will be used as a convention, do not use the replaceable tag in your text or examples.

Use the entities provided by the &FDP;. These entities are found in the common/ folder in the fedora-docs distribution. (Refer also to .) For instance, do not use abbreviations such as "FC2." Instead, use the predefined entities "&FC; &FCVER;," which produces the text "&FC; &FCVER;."