diff options
| author | Karsten Wade <kwade@redhat.com> | 2005-04-28 09:20:15 +0000 |
|---|---|---|
| committer | Karsten Wade <kwade@redhat.com> | 2005-04-28 09:20:15 +0000 |
| commit | bd31c100a2ad1ac8f376d8916404fc410fb4e53c (patch) | |
| tree | 37fd945d35ccbf611e32d00aeae6a0f4e2d00709 | |
| parent | 243baeb660d521f40c5eaab8aa656ac9a6ba9e73 (diff) | |
| download | documentation-guide-bd31c100a2ad1ac8f376d8916404fc410fb4e53c.tar.gz documentation-guide-bd31c100a2ad1ac8f376d8916404fc410fb4e53c.tar.xz documentation-guide-bd31c100a2ad1ac8f376d8916404fc410fb4e53c.zip | |
These changes only reflect the inclusion of the local variables and the associate adjusting of indenting.
| -rw-r--r-- | docs-style-en.xml | 3632 |
1 files changed, 1803 insertions, 1829 deletions
diff --git a/docs-style-en.xml b/docs-style-en.xml index 6480e54..298a211 100644 --- a/docs-style-en.xml +++ b/docs-style-en.xml @@ -1,4 +1,4 @@ - <chapter id="ch-style"> +<chapter id="ch-style"> <!-- @@ -9,93 +9,89 @@ --> - <title>Style</title> + <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 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> - 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. + unnecessary or undefined jargon </para> + </listitem> + <listitem> <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. + grammatical or spelling errors </para> + </listitem> + <listitem> <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: + references to yourself or your experiences </para> - <example> - <title>Incorrect style</title> + </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 @@ -103,1523 +99,1498 @@ 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> + <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. + 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> - <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> + </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> + <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> - <section id="sn-tech-docs-fundamentals"> + <section id="sn-tech-docs-fundamentals"> - <title>Fundamental Concepts of Technical Documentation</title> + <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> + <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> - 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: </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 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"> + </section> - <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 id="sn-fundamentals-3"> - </section> + <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 id="sn-grammar-and-usage"> + </section> + + <section id="sn-grammar-and-usage"> - <title>Grammar and Usage Guidelines</title> + <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> + <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> + 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> + </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> - <section id="sn-composition-tips"> + <section id="sn-composition-tips"> - <title>Composition Tips</title> + <title>Composition Tips</title> <!-- @@ -1631,300 +1602,303 @@ --> + <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> - 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 "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-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> + <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 + 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> + </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-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 + <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> + </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-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-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-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 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> - <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-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> + <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> + <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. + </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> + <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> + </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-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 + <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> - + abbreviations such as "FC2." Instead, use the predefined + entities "&FC; &FCVER;," which produces the text "&FC; + &FCVER;." + </para> </section> - + </section> + + </section> - </chapter> +</chapter> +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-parent-document:("documentation-guide-en.xml" "book" "chapter") +End: +--> |