diff options
| -rw-r--r-- | docs-style-en.xml | 1930 | ||||
| -rw-r--r-- | documentation-guide-en.xml | 9 |
2 files changed, 1936 insertions, 3 deletions
diff --git a/docs-style-en.xml b/docs-style-en.xml new file mode 100644 index 0000000..6480e54 --- /dev/null +++ b/docs-style-en.xml @@ -0,0 +1,1930 @@ + <chapter id="ch-style"> + + <!-- + + To ensure code readability, please use a fill-width of 72 in + Emacs. To set fill width in Emacs, use "C-u 72 C-x f". + + [PWF] + + --> + + <title>Style</title> + + <para> + 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 <emphasis>not</emphasis> contain. Your tutorial + should avoid: + </para> + <itemizedlist> + <listitem> + <para> + excessive wordiness + </para> + </listitem> + <listitem> + <para> + unnecessary or undefined jargon + </para> + </listitem> + <listitem> + <para> + grammatical or spelling errors + </para> + </listitem> + <listitem> + <para> + references to yourself or your experiences + </para> + </listitem> + <listitem> + <para> + remarks which might offend or confuse any reader + </para> + </listitem> + </itemizedlist> + <para> + In this chapter, you will find 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. + </para> + + <section id="sn-intro-to-style"> + + <title>Why Style Is Important</title> + + <para> + Writing well comes naturally to almost no one. It is a skill + that professional writers, even famous ones, must practice + constantly. <firstterm>Style</firstterm> + <indexterm><primary>style</primary></indexterm> is the quality + that separates elegant writing from the merely functional. + </para> + <para> + 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 <citetitle>Ulysses</citetitle><footnote + id='fn-ulysses'> + <para> + See, e.g. <ulink + url="http://www.online-literature.com/james_joyce/ulysses/18/">http://www.online-literature.com/james_joyce/ulysses/18/</ulink>. + Please note that this example contains some mature themes + and language, and is not suitable for all readers. + </para> + </footnote>. 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 his + narrator. + </para> + <para> + 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, idiom, or jargon, a reader or translator may easily + become confused. Take the following example, which compares two + different written executions of the same idea: + </para> + <example> + <title>Incorrect style</title> + + <!-- I prefer "incorrect," because I think terms such as + "problematic" are mealy-mouthed. They remind me of the late + 1980's English textbook trend toward the politically correct yet + wholly unhelpful "standard/nonstandard." But then, I tend to be + dogmatic; it's probably my Catholic upbringing. [PWF] --> + + <para> + 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 <filename>messages</filename> + log. When you see "USB device found," then Bob's your uncle. + </para> + </example> + <example> + <title>Correct style</title> + + <!-- I prefer "correct." See above. [PWF] --> + + <para> + After you complete the configuration changes above, attach the + USB removable media to your system. Use the + <command>dmesg</command> command to examine the kernel message + log. The message <computeroutput>USB device + found</computeroutput> indicates that your device was + installed successfully. + </para> + </example> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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: + </para> + <itemizedlist> + <listitem> + <para> + <citetitle>The Elements of Style</citetitle>, by William + Strunk. Online version: <ulink + url="http://bartleby.com/141/">http://bartleby.com/141/</ulink> + </para> + </listitem> + + <!-- KWade/TFox: Please check citation below, since I don't have + a copy. Thanks! And, um, I'm not sure if I should be using a + formal citation style below. /me is embarrassed. [PWF] --> + + <listitem> + <para> + <citetitle>The Chicago Manual of Style</citetitle>, by the + University of Chicago Press. Online version: <ulink + url="http://www.chicagomanualofstyle.org/">http://www.chicagomanualofstyle.org/</ulink> + </para> + </listitem> + <listitem> + <para> + <citetitle>Paradigm Online Writing Assistant</citetitle>, + maintained by Chuck Guilford, Ph.D. Online only: <ulink + url="http://www.powa.org/">http://www.powa.org/</ulink> + </para> + </listitem> + </itemizedlist> + <para> + There are many free software documentation projects which have + developed their own style guidelines. This chapter, in fact, + draws heavily on the <citetitle>GNOME Documentation Style + Guidelines</citetitle> (<firstterm>GDSG</firstterm>). You may + read the original <citetitle>GDSG</citetitle> at <ulink + url='http://developer.gnome.org/documents/style-guide/'>http://developer.gnome.org/documents/style-guide/</ulink>. + </para> + + </section> + + <section id="sn-tech-docs-fundamentals"> + + <title>Fundamental Concepts of Technical Documentation</title> + + <note> + <title>Bibliographic Information</title> + <para> + This section is drawn primarily from the + <citetitle>GDSG</citetitle>. + </para> + </note> + + <!-- This section will reproduce mostly what is in Chapter 1 of + the GDSG. There may be minor changes. FIXME: Make sure the + appropriate front matter of the Documentation Guide includes + attribution as required by the GNU FDL. --> + + <para> + This chapter provides a brief introduction to writing technical + documentation. + </para> + + <section id="sn-fundamentals-1"> + <title>General Style Requirements</title> + <para> + Technical writing for the &FP; imposes special constraints + beyond the basic requirements of good prose. Good &FED; + technical documentation has the following characteristics: + </para> + <variablelist> + <varlistentry> + <term>Comprehensive</term> + <listitem> + <para> + Describe all of the functionality of a product. Do not + omit functionality that you regard as irrelevant for the + user. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Conformant</term> + <listitem> + <para> + Describe what you see. Do not describe what you want to + see. Present your information in the order that users + experience the subject matter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Clear</term> + <listitem> + <para> + Read <ulink + url="http://www.bartleby.com/141/"><citetitle>The + Elements of Style</citetitle></ulink> to help make + your writing clear. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Consistent</term> + <listitem> + <para> + Use agreed vocabulary throughout your documentation. Use + the same vocabulary as other writers who are working on + related documentation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Concise</term> + <listitem> + <para> + Review your work frequently as you write your document. + Ask yourself which words you can take out. See <xref + linkend="sn-fundamentals-2"/> for a specific + guideline. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sn-fundamentals-2"> + <title>Golden Rules</title> + <para> + This section contains some basic style guidelines. Subsequent + sections in this chapter expand on these guidelines to give + more detailed guidance. + </para> + <variablelist> + <varlistentry> + <term>Golden Rule 1: Be brief.</term> + <listitem> + <itemizedlist> + <listitem> + <para> + Limit each sentence to less than 25 words. + </para> + </listitem> + <listitem> + <para> + Limit each procedure step to 23 words. + </para> + </listitem> + </itemizedlist> + <example id="ex-golden-rule-1-wrong"> + <title>Incorrect: Too long</title> + <para> + 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. + </para> + </example> + <example id="ex-golden-rule-1-right"> + <title>Correct: Less wordy</title> + <para> + Normally, the kernel stores the data in memory prior + to periodically writing the data to the disk. + </para> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term>Golden Rule 2: Be organized.</term> + <listitem> + <itemizedlist> + <listitem> + <para> + Limit each paragraph to one topic. + </para> + </listitem> + <listitem> + <para> + Limit each sentence to one idea. + </para> + </listitem> + <listitem> + <para> + Limit each procedure step to one action. + </para> + </listitem> + </itemizedlist> + <example id="ex-golden-rule-2-wrong"> + <title>Incorrect: Disorganized topics</title> + <para> + The <application>Workspace Switcher</application> + 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 + <emphasis>window manager</emphasis>, allows you to + create more than one virtual desktop, known as + <emphasis>workspaces</emphasis>, to organize your + work, with different applications running in each + workspace. The <application>Workspace + Switcher</application> 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. + </para> + </example> + <example id="ex-golden-rule-2-right"> + <title>Correct: Organized topics</title> + <para> + You can use the <application>Workspace + Switcher</application> to add new + <emphasis>workspaces</emphasis> to the GNOME Desktop. + You can run different applications in each workspace. + The <application>Workspace Switcher</application> + applet provides a miniature map that shows all of your + workspaces. You can use the <application>Workspace + Switcher</application> applet to switch between + workspaces. + </para> + </example> + <tip> + <para> + Plan the order of paragraphs before you start writing. + Decide which topic you want to cover in each + paragraph. + </para> + </tip> + </listitem> + </varlistentry> + <varlistentry> + <term>Golden Rule 3: Be demonstrative.</term> + <listitem> + <para> + Use explicit examples to demonstrate how an application + works. Provide instructions rather than descriptions. + </para> + <example id="ex-golden-rule-3-wrong"> + <title>Incorrect: Describes but does not + demonstrate</title> + <para> + There is a text box that you can use to find out the + definition of a word. + </para> + </example> + <example id="ex-golden-rule-3-right"> + <title>Correct: Demonstrates usage</title> + <para> + To request a definition of a word, type the word in + the text box, then click on the Lookup button. + </para> + </example> + <tip> + <para> + Do not apply this guideline too rigidly. Sometimes you + must explain how software works to support your how-to + examples. + </para> + </tip> + </listitem> + </varlistentry> + <varlistentry id="vle-golden-rule-4"> + <term>Golden Rule 4: Be objective.</term> + <listitem> + <para> + Write in a neutral tone. + </para> + <example id="ex-golden-rule-4-wrong"> + <title>Incorrect: Sentence takes sides</title> + <para> + The applet is a handy little screen grabber. + </para> + </example> + <example id="ex-golden-rule-4-right"> + <title>Correct: Sentence is objective</title> + <para> + Use the applet to take screenshots. + </para> + </example> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section id="sn-fundamentals-3"> + + <title>Tone</title> + <para> + 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: + </para> + <variablelist> + <varlistentry> + <term>Avoid humor</term> + <listitem> + <para> + Humor distracts from the information you are trying to + provide. Humor also makes documentation difficult to + translate. Stay factual. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid personal opinions</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid colloquial language</term> + <listitem> + <para> + Colloquial language is difficult to translate and + usually culture-specific. Stay neutral. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid topical expressions</term> + <listitem> + <para> + An expression that is in common use today might convey + something completely different tomorrow. Stay technical. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid aspirational statements</term> + <listitem> + <para> + Statements about the future developments of a product do + not belong in technical documentation. Write about what + you see right now. Stay real. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sn-fundamentals-4"> + <title>Reaching the Right Audience</title> + <para> + 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. + </para> + </section> + <section id="sn-fundamentals-6"> + <title>User Motivation</title> + <para> + 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. + </para> + </section> + <section id="sn-fundamentals-7"> + <title>New Users</title> + <para> + 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. + You do not need to describe GUI screens, dialogs, and dialog + elements in a tutorial, unless there is an unusual feature + that affects your instructions. + </para> + </section> + <section id="sn-fundamentals-8"> + <title>Experienced Users</title> + <para> + 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. + </para> + </section> + <section id="sn-fundamentals-9"> + <title>Do Not Offend Your Audience</title> + <para> + To avoid offending your readers, apply the following + guidelines to your documentation: + </para> + <variablelist> + <varlistentry> + <term>Avoid insider language</term> + <listitem> + <para> + Insider language includes both undefined jargon and the + tendency of the computer community to shorten words. For + example, use the term <emphasis>documentation</emphasis> + instead of the term <emphasis>docs</emphasis>. You can + identify jargon if terminology fails the following + conditions: + </para> + <itemizedlist> + <listitem> + <para> + A term does not appear in the &FED; Jargon Guide. + </para> + </listitem> + <listitem> + <para> + A term does not appear in the <ulink + url="http://www.bartleby.com/61/"> + <citetitle>American Heritage + Dictionary</citetitle></ulink>. + </para> + </listitem> + <listitem> + <para> + A term does not appear in the glossary of the manual + that you are writing. + </para> + </listitem> + <listitem> + <para> + A term is not defined in the body text of the manual + that you are writing. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid gender-specific language</term> + <listitem> + <para> + Pronoun constructions such as + <emphasis>his/her</emphasis> or + <emphasis>s/he</emphasis> do not exist. There is no need + to identify gender in your instructions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid culture-specific language</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Avoid talking down to your reader</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Other parts of this guide discuss in more detail tone and + language usage that can cause offense. + </para> + + </section> + + </section> + + <section id="sn-grammar-and-usage"> + + <title>Grammar and Usage Guidelines</title> + + <note> + <title>Bibliographical Information</title> + <para> + This section is drawn partly from the <citetitle>GDSG</citetitle>, and + partly from <citetitle>The Elements of Style</citetitle>, updated as + necessary for the needs of 21st-century technical documentation + writers. + </para> + </note> + + <!-- FIXME: Again, check attribution viz. GNU FDL. This will be more work + than the previous section. --> + + <para> + 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, see the <ulink + url="http://www.bartleby.com/61/"> <citetitle>American Heritage + Dictionary </citetitle></ulink> and the <ulink + url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> + <citetitle>Chicago Manual of Style</citetitle></ulink>. + </para> + <variablelist> + <varlistentry> + <term>Abbreviations</term> + <listitem> + <para> + A shortened form of a word or phrase that takes the place + of the full word or phrase, for example Dr., a.m., p.m., + and so on. Apply the following rules when you use + abbreviations: + </para> + <itemizedlist> + <listitem> + <para> + Avoid creating new abbreviations. Unfamiliar + abbreviations can confuse rather than clarify a + concept. + </para> + </listitem> + <listitem> + <para> + Do not explain or expand familiar abbreviations. + </para> + </listitem> + <listitem> + <para> + Do not include familiar abbreviations in the glossary + of your manual. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Adjectives</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Acronyms</term> + <listitem> + <para> + A term that represents a multi-word term. Typically, + acronyms are formed in the following ways: + </para> + <itemizedlist> + <listitem> + <para> + From the first letters of each word in a compound + term, for example Table of Contents (TOC). + </para> + </listitem> + <listitem> + <para> + From recognizable parts of a compound term, such as + GNU Object Model Environment (GNOME). + </para> + </listitem> + </itemizedlist> + <para> + Apply the following rules when you use acronyms: + </para> + <itemizedlist> + <listitem> + <para> + On the first occurrence of an acronym, spell out the + full term, with the acronym in parentheses. + </para> + </listitem> + <listitem> + <para> + Do not spell out the full compound for well-known + acronyms, unless you think the information is useful + for readers. + </para> + </listitem> + <listitem> + <para> + Avoid creating new acronyms. Unfamiliar acronyms can + confuse rather than clarify a concept. + </para> + </listitem> + <listitem> + <para> + Write the acronym in uppercase letters, unless there + is a compelling case for lowercase. + </para> + </listitem> + <listitem> + <para> + Include the acronym and the full term in the glossary + of your manual. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Adverbs</term> + <listitem> + <para> + 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 are: + <emphasis>simply, easily, quickly</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Anthropomorphism</term> + <listitem> + <itemizedlist> + <listitem> + <para> + Do not apply emotions, desires, or opinions to + software applications. + </para> + </listitem> + <listitem> + <para> + Do not apply a sense of location or dimension to a + software application. You can not be + <emphasis>in</emphasis> a text editor. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Articles</term> + <listitem> + <para> + Do not use the definite article <emphasis>the</emphasis> + to begin any of the following items: + </para> + <itemizedlist> + <listitem> + <para> + Manual titles + </para> + </listitem> + <listitem> + <para> + Chapter titles + </para> + </listitem> + <listitem> + <para> + Headings + </para> + </listitem> + <listitem> + <para> + Figure captions + </para> + </listitem> + <listitem> + <para> + Table captions + </para> + </listitem> + <listitem> + <para> + Callouts + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Apostrophe</term> + <listitem> + <para> + Do not use apostrophes except where absolutely + required + </para> + <itemizedlist> + <listitem> + <para> + Do not use apostrophes to denote possession. + </para> + </listitem> + <listitem> + <para> + Do not use apostrophes to denote contractions. + </para> + </listitem> + <listitem> + <para> + Do not use apostrophes to denote plurals. + </para> + </listitem> + </itemizedlist> + <example id="ex-apostrophe-wrong"> + <title>Incorrect: Apostrophes</title> + <itemizedlist> + <listitem> + <para> + the <guimenu>Main Menu's</guimenu> + <guimenuitem>Help</guimenuitem> option + </para> + </listitem> + <listitem> + <para> + don't use the default option + </para> + </listitem> + <listitem> + <para> + several SCSI disk's + </para> + </listitem> + </itemizedlist> + </example> + <example id="ex-apostrophe-right"> + <title>Correct: No apostrophes</title> + <itemizedlist> + <listitem> + <para> + the <guimenuitem>Help</guimenuitem> option on the + <guimenu>Main Menu</guimenu> + </para> + </listitem> + <listitem> + <para> + do not use the default option + </para> + </listitem> + <listitem> + <para> + several SCSI disks + </para> + </listitem> + </itemizedlist> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term>Brackets</term> + <listitem> + <itemizedlist> + <listitem> + <para> + Do not use brackets [such as these] as a substitute + for parentheses (such as these). + </para> + </listitem> + <listitem> + <para> + Use brackets for optional command line entries. + </para> + </listitem> + <listitem> + <para> + Do not use angle brackets to indicate variables in + text, instead use the <emphasis>replaceable</emphasis> + tag. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Capitalization</term> + <listitem> + <para> + Capitalize in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + All letters in acronyms, unless the acronym is a + well-known exception + </para> + </listitem> + <listitem> + <para> + Initial letter of the first word in a list + </para> + </listitem> + <listitem> + <para> + Initial letter of the first word in a callout + </para> + </listitem> + <listitem> + <para> + Initial letter of a key name, such as the + <keycap>Shift</keycap> key + </para> + </listitem> + <listitem> + <para> + Initial letter of a sentence. Avoid starting a + sentence with a command name or application name that + has a lowercase initial letter + </para> + </listitem> + <listitem> + <para> + Initial letter of a complete sentence after a colon + </para> + </listitem> + </itemizedlist> + <para> + Do not capitalize in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + A compound term that is followed by an abbreviation or + an acronym + </para> + </listitem> + <listitem> + <para> + When you want to emphasize something + </para> + </listitem> + <listitem> + <para> + Variable names + </para> + </listitem> + <listitem> + <para> + The initial letter of the first word following a + colon, if the word is part of an incomplete sentence + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Captions</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Colon</term> + <listitem> + <para> + Use a colon in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + To introduce a list + </para> + </listitem> + <listitem> + <para> + Before an explanation + </para> + </listitem> + <listitem> + <para> + After an introduction + </para> + </listitem> + </itemizedlist> + <para> + Do not use a colon in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + To introduce a figure or a table + </para> + </listitem> + <listitem> + <para> + To introduce headings + </para> + </listitem> + <listitem> + <para> + At the end of an introduction to a procedure + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Column headings</term> + <listitem> + <para> + Use the same rules as for headings. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Comma</term> + <listitem> + <para> + Use commas in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + To separate items in a series + </para> + </listitem> + <listitem> + <para> + To separate the parts of a sentence + </para> + </listitem> + <listitem> + <para> + To separate nonrestrictive phrases + </para> + </listitem> + <listitem> + <para> + Instead of dashes to set off appositives + </para> + </listitem> + <listitem> + <para> + With <emphasis>for example</emphasis> and similar + expressions + </para> + </listitem> + </itemizedlist> + <para> + Do not use commas in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + In a series of adjectives used as one modifier + </para> + </listitem> + <listitem> + <para> + Between two short independent clauses + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Commands</term> + <listitem> + <para> + Do not use commands as verbs. + </para> + </listitem> + </varlistentry> + <varlistentry id="vle-contractions"> + <term>Contractions</term> + <listitem> + <para> + Do not use contractions such as + <emphasis>can't</emphasis>, <emphasis>don't</emphasis>, or + <emphasis>isn't</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Dash</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Ellipsis</term> + <listitem> + <para> + Use an ellipsis in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + To show that you have omitted something from a + sentence + </para> + </listitem> + <listitem> + <para> + To indicate a pause when you quote displayed text + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Fractions</term> + <listitem> + <para> + Follow these rules when using fractions: + </para> + <itemizedlist> + <listitem> + <para> + Use numerals for fractions in tables and in units of + measurement, but spell out fractions in prose. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + If a fraction is used in a compound modifier, insert a + hyphen between the fraction and the unit of + measurement. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Gender</term> + <listitem> + <para> + See <xref linkend="sn-fundamentals-9"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Grammar</term> + <listitem> + <para> + Use standard American English grammar rules, see the + <ulink + url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> + <citetitle>Chicago Manual of Style</citetitle></ulink>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Headings</term> + <listitem> + <para> + Use the following capitalization rules in headings: + </para> + <itemizedlist> + <listitem> + <para> + Initial uppercase letter of the first word + </para> + </listitem> + <listitem> + <para> + Initial uppercase letter for all nouns, adjectives, + and verbs. + </para> + </listitem> + <listitem> + <para> + All lowercase letters for conjunctions, articles, and + prepositions of less than four letters + </para> + </listitem> + <listitem> + <para> + Initial uppercase letter for prepositions of four + letters or longer + </para> + </listitem> + <listitem> + <para> + Initial uppercase letter for conjunctions of four + letters or longer + </para> + </listitem> + </itemizedlist> + <!-- <para> See <xref linkend="infodesign-2"/> for more + information about headings. </para> --> + </listitem> + </varlistentry> + <varlistentry> + <term>Hyphen</term> + <listitem> + <para> + Use hyphens in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + With a numeral in a compound modifier + </para> + </listitem> + <listitem> + <para> + To prevent ambiguity + </para> + </listitem> + <listitem> + <para> + With some standard prefixes and suffixes. Use the + <ulink url="http://www.bartleby.com/61/"> + <citetitle>American Heritage + Dictionary</citetitle></ulink> for guidance + </para> + </listitem> + <listitem> + <para> + In spelled-out fractions + </para> + </listitem> + <listitem> + <para> + In variable names of two or more words, such as + <replaceable> directory-name</replaceable>. Note: + <replaceable>filename</replaceable> is an exception. + </para> + </listitem> + </itemizedlist> + <para> + Do not use hyphens in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + For industry-accepted terms + </para> + </listitem> + <listitem> + <para> + To construct verbs + </para> + </listitem> + <listitem> + <para> + With an adverb ending in <emphasis>ly</emphasis> + </para> + </listitem> + <listitem> + <para> + With numerals as single modifiers + </para> + </listitem> + <listitem> + <para> + With a word that is listed as unhyphenated in the + <ulink url="http://www.bartleby.com/61/"> + <citetitle>American Heritage + Dictionary</citetitle></ulink>, and that uses a + common prefix + </para> + </listitem> + <listitem> + <para> + With trademarked terms + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Latin terms</term> + <listitem> + <para> + Do not use Latin terms. Use an equivalent English term + instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Like</term> + <listitem> + <para> + Do not use the term <emphasis>like</emphasis> to + denote equivalence or similarity. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Lists</term> + <listitem> + <para> + Introduce a list with a complete sentence that ends with a + colon. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Numbers</term> + <listitem> + <para> + Spell out numbers in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + Numbers from zero through nine unless the number + is part of a measurement + </para> + </listitem> + <listitem> + <para> + Approximations + </para> + </listitem> + <listitem> + <para> + Extreme values such as <emphasis>million</emphasis>, + but precede the value with a numeral + </para> + </listitem> + <listitem> + <para> + Any number that begins a sentence + </para> + </listitem> + <listitem> + <para> + A number that is immediately followed by a numeral, + for example: two 10 MB files + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Numerals</term> + <listitem> + <para> + Use numerals in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + The number 10 or greater + </para> + </listitem> + <listitem> + <para> + Negative numbers + </para> + </listitem> + <listitem> + <para> + Most fractions + </para> + </listitem> + <listitem> + <para> + Percentages + </para> + </listitem> + <listitem> + <para> + Decimals + </para> + </listitem> + <listitem> + <para> + Measurements + </para> + </listitem> + <listitem> + <para> + Units of time smaller than one second + </para> + </listitem> + <listitem> + <para> + References to bits and bytes + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Parentheses</term> + <listitem> + <para> + Use parentheses in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + To contain the abbreviation of a term on the first + occurrence of the full term + </para> + </listitem> + <listitem> + <para> + In man page references, specifically the section + number + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Period</term> + <listitem> + <para> + Use a period in the following situations: + </para> + <itemizedlist> + <listitem> + <para> + To end a sentence + </para> + </listitem> + <listitem> + <para> + In file and directory names + </para> + </listitem> + <listitem> + <para> + In abbreviations that can be mistaken for words, such + as a.m. and U.S. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Punctuation</term> + <listitem> + <para> + Use standard American English punctuation rules. In + addition to the specific points of punctuation in this + section, see also the <ulink + url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> + <citetitle>Chicago Manual of Style</citetitle></ulink>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Punctuation in numbers</term> + <listitem> + <para> + Do not use a comma in numerals of four digits. Use a comma + in numerals of more than four digits. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Quotation marks</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Semicolon</term> + <listitem> + <para> + Do not use semicolons. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Slash</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Spelling</term> + <listitem> + <para> + Use standard American English spelling rules, see the + <ulink url="http://www.bartleby.com/61/"> + <citetitle>American Heritage + Dictionary</citetitle></ulink> for guidelines. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Titles</term> + <listitem> + <para> + For manual titles use the same rules as for headings. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Units</term> + <listitem> + <para> + Follow these rules when using units: + </para> + <itemizedlist> + <listitem> + <para> + Use standard abbreviations for units of measurements, + do not invent your own abbreviations. + </para> + </listitem> + <listitem> + <para> <!-- See <xref linkend="units"/> for a list of + units relevant to the GNOME Desktop. --> For further + guidelines, see the <citetitle>IEEE Standard + Dictionary of Electrical and Electronics + Terms</citetitle>. + </para> + </listitem> + <listitem> + <para> + Use periods for abbreviated units that might be + mistaken for a word. + </para> + </listitem> + <listitem> + <para> + Most standard abbreviations of units account for both + singular and plural usage. + </para> + </listitem> + <listitem> + <para> + Insert a space between the numeral and the unit of + measurement. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section id="sn-composition-tips"> + + <title>Composition Tips</title> + +<!-- + + This section will collect miscellanea and advice for specific situations + that the &FDP; editors encounter. I hope they will feel free to e-mail + me sticky situations or particularly interesting examples of work + they've beautified. Hopefully not too much will be drawn from my own + work! + +--> + + <para> + 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. + </para> + + <section id="sn-misc-active-voice"> + <title>Active Voice</title> + <para> + 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 + "should," "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. + </para> + <example id="ex-misc-passive-voice"> + <title>Incorrect: Passive voice</title> + <para> + The <command>yum update</command> command must be run. + </para> + <para> + You should run the <command>yum update</command> command. + </para> + </example> + <example id="ex-misc-active-voice"> + <title>Correct: Active voice</title> + <para> + Run the <command>yum update</command> command. + </para> + </example> + </section> + + <section id="sn-present-tense"> + <title>Present Tense</title> + <para> + 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; see also + <xref + linkend="sn-misc-active-voice"/>. + </para> + <example id="ex-misc-future-tense"> + <title>Incorrect: Future tense</title> + <para> + The application will display a list of target files. + </para> + <para> + A list of target files will be displayed by the application. + </para> + </example> + <example id="ex-misc-present-tense"> + <title>Correct: Present tense</title> + <para> + The application displays a list of target files. + </para> + </example> + </section> + + <section id="sn-narrative-voice"> + <title>Narrative Voice</title> + <para> + 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." + </para> + <example id="ex-misc-wrong-person"> + <title>Incorrect: First or third person</title> + <para> + As described in the last section, I always run + <command>up2date</command> before configuring the Samba + server. + </para> + <para> + If the user needs to back up his or her files, s/he should + use the <command>tar</command> or <command>cpio</command> + command. + </para> + </example> + <example id="ex-misc-correct-person"> + <title>Correct: Second (or no) person</title> + <para> + Refer to the section on <command>up2date</command> before + configuring the Samba server. + </para> + <para> + Users can back up files with the <command>tar</command> or + <command>cpio</command> command. + </para> + </example> + </section> + + <section id="sn-misc-negative"> + <title>Negative Words</title> + <para> + 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 <emphasis>don't</emphasis> or + <emphasis>can't</emphasis>. See <xref + linkend="vle-contractions" />. + </para> + </section> + + <section id="sn-misc-uncertainty"> + <title>Uncertainty</title> + <para> + 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. + </para> + </section> + + <section id="sn-misc-offtopic"> + <title>Redundant Coverage</title> + <para> + 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. + </para> + </section> + + <section id="sn-misc-importance"> + <title>Self-referential Value Judgments</title> + <para> + Avoid statements like "One of the most important things to do + is <replaceable>XYZ</replaceable>." 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 + <replaceable>XYZ</replaceable>." Then elaborate as required. + If the whole section concerns how to do + <replaceable>XYZ</replaceable>, leave this sentence out + entirely. See also <xref linkend="vle-golden-rule-4" />. + </para> + </section> + + <section id="sn-misc-precision"> + <title>Precision of Language</title> + <para> + Use precise words for actions users should take. Do not + instruct users to "go" to a selection, or "find" a menu. + </para> + <example id="ex-precision-wrong"> + <title>Incorrect: Imprecise wording</title> + <itemizedlist> + <listitem> + <para> + Go to the <guimenu>Main Menu</guimenu> -> + <guimenuitem>Foobar</guimenuitem> + </para> + </listitem> + <listitem> + <para> + Find the option labeled <guilabel>Search</guilabel> + </para> + </listitem> + </itemizedlist> + </example> + <example id="ex-precision-right"> + <title>Correct: Precise wording</title> + <itemizedlist> + <listitem> + <para> + From the <guimenu>Main Menu</guimenu>, select + <guimenuitem>Foobar</guimenuitem> + </para> + </listitem> + <listitem> + <para> + Select the <guilabel>Search</guilabel> option + </para> + </listitem> + </itemizedlist> + </example> + <important> + <title>Do Not Discriminate Against Non-GUI Users</title> + <para> + 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. + </para> + </important> + + </section> + + <section id="sn-misc-docbook-tips"> + <title>DocBook Tips</title> + <para> + This section contains tips on how to use DocBook tags more + effectively in your documentation. + </para> + + <section id="sn-misc-admonitions"> + <title>Admonitions</title> + <para> + Avoid overuse of admonitions. Use only the most important + material inside the admonition. Doing so will keep + admonitions short and effective. Any background material + required to explain the most important admonition statements + should be moved outside the admonition. + </para> + <example id="ex-misc-ineffective-admonition"> + <title>Incorrect: Lengthy admonition</title> + <para> + <warning> + <title>Using <command>sfdisk</command></title> + <para> + The <command>sfdisk</command> command accepts a script + file as standard input to set up partitions on a hard + disk. Sometimes <command>sfdisk</command> 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 + <command>sfdisk -n</command> command to check your + input file before writing to the disk. + </para> + </warning> + </para> + </example> + <example id="ex-misc-good-admonition"> + <title>Correct: Brief admonition</title> + <para> + The <command>sfdisk</command> command accepts a script + file as standard input to set up partitions on a hard + disk. Sometimes <command>sfdisk</command> will simply + reject an erroneous input file. In other cases, it will + use the input verbatim, writing an incorrect partition + table to your disk. + <warning> + <title>Using <command>sfdisk</command></title> + <para> + Always use the <command>sfdisk -n</command> command to + check your input file before writing to the disk. + </para> + </warning> + </para> + </example> + <para> + 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"). + </para> + </section> + + <section id="sn-misc-replaceable"> + <title>The <replaceable> Tag</title> + <para> + 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. + </para> + </section> + + <section id="sn-misc-entities"> + <title>XML Entities</title> + <para> + Use the entities provided by the &FDP;. These entities are + found in the <filename>common/</filename> folder in the + <filename>fedora-docs</filename> distribution. (See also + <xref + linkend="ch-getting-files"/>.) For instance, do not use + abbreviations such as "FC2." Instead, use the predefined + entities "&FC; &FCVER;," which produces the text + "&FC; &FCVER;." + </para> + </section> + + </section> + + </section> + + </chapter> diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml index f2f37ea..eae73bb 100644 --- a/documentation-guide-en.xml +++ b/documentation-guide-en.xml @@ -1,8 +1,9 @@ -<!-- $Id: documentation-guide-en.xml,v 1.16 2004/09/13 02:03:22 tfox Exp $ --> - +<!-- $Id: documentation-guide-en.xml,v 1.17 2005/04/28 08:55:41 kwade Exp $ --> +<!-- breaks the build ... <?xml version="1.0" encoding="utf-8"?> --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!-- *************** Bring in Fedora entities *************** --> <!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml"> %FEDORA-ENTITIES-EN; @@ -24,7 +25,7 @@ <!ENTITY CONVERTING SYSTEM "docs-converting-en.xml"> <!ENTITY CVS SYSTEM "../common/cvs-en.xml"> <!ENTITY ACKNOWLEDGMENTS SYSTEM "acknowledgments-en.xml"> - +<!ENTITY STYLE SYSTEM "docs-style-en.xml"> ]> @@ -73,6 +74,8 @@ &TUTORIAL; + &STYLE; + &CONVERTING; &CVS; |