diff options
| author | Paul W. Frields <stickster@gmail.com> | 2005-04-29 18:33:42 +0000 |
|---|---|---|
| committer | Paul W. Frields <stickster@gmail.com> | 2005-04-29 18:33:42 +0000 |
| commit | e5d2f6d3c40db868a84d7c77dcbe52eb6c32fb37 (patch) | |
| tree | 1e59bc26298684faa9949149ec537efcd96a8306 | |
| parent | aa790df9959a780792e2da0e2dae4115ddbf8196 (diff) | |
| download | documentation-guide-e5d2f6d3c40db868a84d7c77dcbe52eb6c32fb37.tar.gz documentation-guide-e5d2f6d3c40db868a84d7c77dcbe52eb6c32fb37.tar.xz documentation-guide-e5d2f6d3c40db868a84d7c77dcbe52eb6c32fb37.zip | |
Added Id tag, cleanup, and additional editing to eliminate inconsistency
| -rw-r--r-- | docs-style-en.xml | 2159 |
1 files changed, 1085 insertions, 1074 deletions
diff --git a/docs-style-en.xml b/docs-style-en.xml index 72be8de..35b7636 100644 --- a/docs-style-en.xml +++ b/docs-style-en.xml @@ -1,22 +1,15 @@ -<chapter id="ch-style"> - - <!-- - - To ensure code readability, please use a fill-width of 72 in - Emacs. To set fill width in Emacs, use "C-u 72 C-x f". - - [PWF] - - --> +<!-- $Id: --> +<chapter id="ch-style"> + <title>Style</title> <para> Writing good technical documentation is not simply reproducing - command lines and instruction sets. Good documentation is easy to + 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 + progression of concepts. Good documentation can also be defined by + what it does <emphasis>not</emphasis> contain. Your tutorial should avoid: </para> <itemizedlist> @@ -47,110 +40,119 @@ </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 + This chapter contains style rules and guidelines for writing &FED; + documentation. Guidelines are not the same as rules. It is + acceptable to violate a guideline when it makes your material easier + to understand. Follow guidelines whenever possible, but follow + rules at all times. Assume any advice is a guideline unless identified otherwise. </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 + 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. + 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'> + 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> For example, refer to. <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. + 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 + </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 + disorganized but loosely connected thought patterns of the 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 + 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, + or they might be reading a translation. If the writer uses slang, idioms, or jargon, a reader or translator may easily become - confused. Take the following example, which compares two different - written executions of the same idea: + confused. The following example compares two different written + executions of the same idea: </para> <example> - <title>Incorrect style</title> + <title>Incorrect style</title> <!-- I prefer "incorrect," because I think terms such as - "problematic" are mealy-mouthed. They remind me of the late + "problematic" are mealy-mouthed. They remind me of the late 1980's English textbook trend toward the politically correct yet wholly unhelpful "standard/nonstandard." But then, I tend to be dogmatic; it's probably my Catholic upbringing. [PWF] --> <para> So you made the changes I showed you in the last section. What's - the next thing you should do? Just pop your thumb drive onto - your system and read the <filename>messages</filename> log. When - you see "USB device found," then Bob's your uncle. + 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> + <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. + 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 + </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 + 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> + 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> + Strunk. Online version: <ulink + url="http://bartleby.com/141/">http://bartleby.com/141/</ulink> </para> </listitem> <!-- placeholder for when it's ready @@ -159,54 +161,47 @@ Strunk. Fedora Docs Project version: <ulink url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink> </para> ---> - <!-- 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] --> - - <!-- this is the way to do it, you are correct. - kwade --> - <!-- comments may now be self-destructed --> - +--> <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> + 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> + 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 + 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>. + url='http://developer.gnome.org/documents/style-guide/'>http://developer.gnome.org/documents/style-guide/</ulink>. </para> - + </section> - + <section id="sn-tech-docs-fundamentals"> - + <title>Fundamental Concepts of Technical Documentation</title> - + <note> <title>Bibliographic Information</title> <para> This section is drawn primarily from the - <citetitle>GDSG</citetitle>. + <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 + 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. --> @@ -219,79 +214,81 @@ <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: + 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. + 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> <!-- I'm having issues with the + <varlistentry> + <term>Conforming</term> <!-- I'm having issues with the sketchy definition of this non-dictionary word and the associated text. Not wrong, per se, just wishing for something better. This note shall remind us! - kwade --> + <!-- Hopefully this change helps. Makes sense according to the + gdict tool in Core, at least. - PWF --> <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> + 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 <citetitle>The Elements of Style</citetitle> (<ulink - url="http://www.bartleby.com/141/">http://www.bartleby.com/141/</ulink>) - to help make your writing clear. + url="http://www.bartleby.com/141/">http://www.bartleby.com/141/</ulink>) + to help make your writing clear. </para> <!-- placeholder for when this is published: <para> Read <citetitle>The Elements of Style</citetitle> &FED;-version (<ulink - url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>) + url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>) to help make your writing clear. </para> --> - </listitem> - </varlistentry> - <varlistentry> - <term>Consistent</term> - <listitem> + </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> + 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. Refer to <xref + Ask yourself which words you can take out. Refer to <xref linkend="sn-fundamentals-2"/> for specific guidelines. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sn-fundamentals-2"> - <title>Golden Rules</title> + </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. + This section contains some basic style guidelines. Subsequent + sections in this chapter expand on these guidelines to give more + detailed guidance. </para> <variablelist> <varlistentry> @@ -312,16 +309,16 @@ <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. + 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. + periodically writing the data to the disk. </para> </example> </listitem> @@ -333,55 +330,54 @@ <listitem> <para> Limit each paragraph to one topic. - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Limit each sentence to one idea. - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Limit each procedure step to one action. - </para> - </listitem> + </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. + 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. + 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. + Decide which topic you want to cover in each paragraph. </para> </tip> </listitem> @@ -391,28 +387,28 @@ <listitem> <para> Use explicit examples to demonstrate how an application - works. Provide instructions rather than descriptions. + works. Provide instructions rather than descriptions. </para> <example id="ex-golden-rule-3-wrong"> <title>Incorrect: Describes but does not - demonstrate</title> + demonstrate</title> <para> There is a text box that you can use to find out the - definition of a word. + 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. + text box, then select <guilabel>Lookup</guilabel>. </para> </example> <tip> <para> - Do not apply this guideline too rigidly. Sometimes you - must explain how software works to support your how-to - examples. + Do not apply this guideline too rigidly. Sometimes you + must explain how software works to support your how-to + examples. </para> </tip> </listitem> @@ -421,12 +417,12 @@ <term>Golden Rule 4: Be objective</term> <listitem> <para> - Write in a neutral tone. + 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. + The applet is a handy little screen grabber. </para> </example> <example id="ex-golden-rule-4-right"> @@ -439,209 +435,208 @@ </varlistentry> </variablelist> - </section> + </section> - <section id="sn-fundamentals-3"> + <section id="sn-fundamentals-3"> - <title>Tone</title> + <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: + Inappropriate tone hinders reader access to information. A + neutral tone free of opinion or personal flavor improves the + reader's comprehension. Neutral tone helps writers to work in + parallel on a large technical documentation project. + Furthermore, additional writers may join the project at any + time. Use of a neutral tone helps to achieve consistency across + a documentation set, and thereby facilitates user access to + information. The best way to achieve a common, neutral tone is + to apply the following principles: </para> - <variablelist> - <varlistentry> - <term>Avoid humor</term> - <listitem> + <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> + 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> + 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> + 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> + 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> + 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> + </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> + content of a manual follow from an understanding of the + audience. Consider how the audience accesses the documentation, + what sort of information the audience needs, and the experience + level of the audience. Usually, you need to create + documentation that is suitable for different audiences. The + following sections introduce some of the audience-related topics + you need to consider. + </para> </section> - <section id="sn-fundamentals-6"> - <title>User Motivation</title> + <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> + 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> + guidance about unfamiliar applications or functionality. Each + tutorial should contain enough introductory information to tell + new users how to start using the relevant functions. Each + tutorial should also contain enough usage instructions to tell + users the different actions that they can perform with the + command or function. Keep these instructions task-oriented. Do + not describe GUI screens, dialogs, and dialog elements in a + tutorial, unless there is an unusual feature that affects your + instructions. + </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> + 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: + to your documentation: </para> - <variablelist> - <varlistentry> - <term>Avoid insider language</term> - <listitem> + <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: + tendency of the computer community to shorten words. For + example, use the term <literal>documentation</literal> + instead of the term <literal>docs</literal>. A term may + be jargon if it fails all the following conditions: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> - A term does not appear in the <citetitle>&FED; Jargon - Buster</citetitle> (<ulink - url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>). - </para> - </listitem> - <listitem> + The term does not appear in the <citetitle>&FED; + Jargon Buster</citetitle> (<ulink + url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>). + </para> + </listitem> + <listitem> <para> - A term does not appear in the <citetitle>American - Heritage Dictionary</citetitle> (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/ - </ulink>). - </para> - </listitem> - <listitem> + The term does not appear in the <citetitle>American + Heritage Dictionary</citetitle> (<ulink + url="http://www.bartleby.com/61/">http://www.bartleby.com/61/ + </ulink>). + </para> + </listitem> + <listitem> <para> - A term does not appear in the glossary of the manual - that you are writing. - </para> - </listitem> - <listitem> + The 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> + The 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> + </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> + Pronoun constructions such as <literal>his/her</literal> + or <literal>s/he</literal> 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> + 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> + 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> + language usage that can cause offense. + </para> - </section> + </section> - </section> + </section> <section id="sn-grammar-and-usage"> @@ -651,205 +646,208 @@ <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. + <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 + <!-- 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 for use in &FED; documentation. Many of these guidelines are only applicable to English-language usage, refer to the <citetitle>American Heritage Dictionary</citetitle> (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) + url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) and the <citetitle>Chicago Manual of Style</citetitle> (<ulink - url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) - </para> - <variablelist> - <varlistentry> - <term>Abbreviations</term> - <listitem> + url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</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> + the full word or phrase, such as <literal>Dr.</literal>, + <literal>a.m.</literal>, <literal>p.m.</literal>, 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> + </listitem> + <listitem> <para> Do not include familiar abbreviations in the glossary of - your manual. - </para> - </listitem> + your manual. + </para> + </listitem> </itemizedlist> <para> - For abbreviations of phrases, such as i.e. for "in other - words" and e.g. for "for example", do not use the - abbreviation. Spell out the entire phrase. + For abbreviations of phrases, such as + <literal>i.e.</literal> for "in other words" and + <literal>e.g.</literal> for "for example", do not use the + abbreviation. Spell out the entire phrase. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Adjectives</term> - <listitem> + </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. + 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> + </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> + 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> + 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> + Object Model Environment (GNOME). + </para> + </listitem> </itemizedlist> <para> Apply the following rules when you use acronyms: - </para> - <itemizedlist> - <listitem> + </para> + <itemizedlist> + <listitem> <para> On the first occurrence of an acronym, spell out the - full term, with the acronym in parentheses. - </para> - </listitem> - <listitem> + 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> + 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> + a compelling case for lowercase. + </para> + </listitem> + <listitem> <para> Include the acronym and the full term in the glossary of - your manual. - </para> - </listitem> + your manual. + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Adverbs</term> - <listitem> + </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>. + 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 + <literal>simply</literal>, <literal>easily</literal>, + <literal>quickly</literal>. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Anthropomorphism</term> - <listitem> - <itemizedlist> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Anthropomorphism</term> + <listitem> + <itemizedlist> + <listitem> <para> Do not apply emotions, desires, or opinions to software - applications. - </para> - </listitem> - <listitem> + 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> + software application. A user can not be "in" a text + editor. + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Articles</term> - <listitem> + </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> + Do not use the definite article <literal>the</literal> to + begin any of the following items: + </para> + <itemizedlist> + <listitem> <para> Manual titles - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Chapter titles - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Headings - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Figure captions - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Table captions - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Callouts - </para> - </listitem> + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Apostrophe</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Apostrophe</term> + <listitem> <para> Do not use apostrophes except where absolutely required </para> @@ -857,18 +855,18 @@ <listitem> <para> Do not use apostrophes to denote possession. - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Do not use apostrophes to denote contractions. - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Do not use apostrophes to denote plurals. - </para> - </listitem> + </para> + </listitem> </itemizedlist> <example id="ex-apostrophe-wrong"> <title>Incorrect: Apostrophes</title> @@ -876,7 +874,7 @@ <listitem> <para> the <guimenu>Main Menu's</guimenu> - <guimenuitem>Help</guimenuitem> option + <guimenuitem>Help</guimenuitem> option </para> </listitem> <listitem> @@ -897,7 +895,7 @@ <listitem> <para> the <guimenuitem>Help</guimenuitem> option on the - <guimenu>Main Menu</guimenu> + <guimenu>Main Menu</guimenu> </para> </listitem> <listitem> @@ -913,120 +911,125 @@ </itemizedlist> </example> </listitem> - </varlistentry> - <varlistentry> - <term>Brackets</term> - <listitem> - <itemizedlist> - <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> + parentheses (such as these). + </para> + </listitem> + <listitem> <para> Use brackets for optional command line entries. - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Do not use angle brackets to indicate variables in text, - instead use the - <replaceable><replaceable></replaceable> tag. - Refer to <xref linkend="s1-xml-tags-replaceable"/> for - information about using this tag. + instead use the <sgmltag + class="starttag">replaceable</sgmltag> tag. Refer to + <xref linkend="s1-xml-tags-replaceable"/> for + information about using this tag. </para> - </listitem> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Capitalization</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Capitalization</term> + <listitem> <para> Capitalize in the following situations: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> All letters in acronyms, unless the acronym is a - well-known exception - </para> - </listitem> - <listitem> + well-known exception + </para> + </listitem> + <listitem> <para> Initial letter of the first word in a list - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Initial letter of the first word in a callout - </para> - </listitem> - <listitem> + </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> + <keycap>Shift</keycap> key + </para> + </listitem> + <listitem> + <para> + Initial letter of a sentence + </para> + <note> + <title>Command Names</title> + <para> + Avoid starting a sentence with a command name or + application name that has a lowercase initial letter. + </para> + </note> + </listitem> + <listitem> <para> Initial letter of a complete sentence after a colon - </para> - </listitem> - </itemizedlist> + </para> + </listitem> + </itemizedlist> <para> - Do not capitalize in the following situations: + Do not capitalize in the following situations: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> A compound term that is followed by an abbreviation or - an acronym - </para> - </listitem> - <listitem> + an acronym + </para> + </listitem> + <listitem> <para> When you want to emphasize something - </para> - </listitem> - <listitem> + </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> + </para> + </listitem> + <listitem> + <para> + The initial letter of an incomplete sentence after a + colon + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Captions</term> - <listitem> + </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> + 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: + Use a colon in the following situations: </para> <itemizedlist> <listitem> @@ -1065,573 +1068,576 @@ </para> </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Column headings</term> - <listitem> + </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> + </listitem> + </varlistentry> + <varlistentry> + <term>Comma</term> + <listitem> <para> - Use commas in the following situations: + Use commas in the following situations: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> To separate items in a series - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> To separate the parts of a sentence - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> To separate nonrestrictive phrases - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Instead of dashes to set off appositives - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> With <emphasis>for example</emphasis> and similar - expressions - </para> - </listitem> + expressions + </para> + </listitem> </itemizedlist> <para> - Do not use commas in the following situations: + Do not use commas in the following situations: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> In a series of adjectives used as one modifier - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Between two short independent clauses - </para> - </listitem> + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Commands</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Commands</term> + <listitem> <para> - Do not use commands as verbs. + Do not use commands as verbs. </para> - </listitem> - </varlistentry> - <varlistentry id="vle-contractions"> - <term>Contractions</term> - <listitem> + </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>. + <emphasis>don't</emphasis>, or <emphasis>isn't</emphasis>. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Dash</term> - <listitem> + </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. + 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> + </listitem> + </varlistentry> + <varlistentry> + <term>Ellipsis</term> + <listitem> <para> Use an ellipsis in the following situations: - </para> - <itemizedlist> - <listitem> + </para> + <itemizedlist> + <listitem> <para> - To show that you have omitted something from a sentence - </para> - </listitem> - <listitem> + 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> + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Fractions</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Fractions</term> + <listitem> <para> Follow these rules when using fractions: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> Use numerals for fractions in tables and in units of - measurement, but spell out fractions in prose. - </para> - </listitem> - <listitem> + 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> + 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> + hyphen between the fraction and the unit of measurement. + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Gender</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Gender</term> + <listitem> <para> Refer to <xref linkend="sn-fundamentals-9"/>. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Grammar</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Grammar</term> + <listitem> <para> Use standard American English grammar rules, refer to the - <citetitle>Chicago Manual of Style</citetitle> (<ulink - url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> - http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) + <citetitle>Chicago Manual of Style</citetitle> (<ulink + url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> + http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Headings</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Headings</term> + <listitem> <para> Use the following capitalization rules in headings: - </para> - <itemizedlist> - <listitem> + </para> + <itemizedlist> + <listitem> <para> Initial uppercase letter of the first word </para> - </listitem> - <listitem> + </listitem> + <listitem> <para> Initial uppercase letter for all nouns, adjectives, and - verbs. - </para> - </listitem> - <listitem> + verbs. + </para> + </listitem> + <listitem> <para> All lowercase letters for conjunctions, articles, and - prepositions of fewer than four letters - </para> - </listitem> - <listitem> + prepositions of fewer than four letters + </para> + </listitem> + <listitem> <para> Initial uppercase letter for prepositions of four - letters or longer - </para> - </listitem> - <listitem> + 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 + 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> + </listitem> + </varlistentry> + <varlistentry> + <term>Hyphen</term> + <listitem> <para> - Use hyphens in the following situations: + Use hyphens in the following situations: </para> - <itemizedlist> - <listitem> - <para> With a numeral in a compound modifier - </para> - </listitem> - <listitem> + <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 - <citetitle>American Heritage Dictionary</citetitle> - (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) - for guidance - </para> - </listitem> - <listitem> - <para> - In spelled-out fractions - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> + <para> + With some standard prefixes and suffixes. Use the + <citetitle>American Heritage Dictionary</citetitle> + (<ulink + url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</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> + <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> + Do not use hyphens in the following situations: + </para> + <itemizedlist> + <listitem> <para> For industry-accepted terms - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> To construct verbs - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> With an adverb ending in <emphasis>ly</emphasis> - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> - With numerals as single modifiers - </para> - </listitem> - <listitem> + With numerals as single modifiers + </para> + </listitem> + <listitem> <para> With a word that is listed as unhyphenated in the - <citetitle>American Heritage Dictionary</citetitle> - (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>), - and that uses a common prefix - </para> - </listitem> - <listitem> + <citetitle>American Heritage Dictionary</citetitle> + (<ulink + url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</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> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Latin terms</term> + <listitem> <para> - Do not use Latin terms. Use an equivalent English term - instead. + Do not use Latin terms. Use an equivalent English term + instead. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Like</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Like</term> + <listitem> <para> Do not use the term <emphasis>like</emphasis> to denote - equivalence or similarity. + equivalence or similarity. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Lists</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Lists</term> + <listitem> <para> Introduce a list with a complete sentence that ends with a - colon. + colon. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Numbers</term> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term>Numbers</term> + <listitem> <para> Spell out numbers in the following situations: </para> - <itemizedlist> - <listitem> + <itemizedlist> + <listitem> <para> Numbers from zero through nine unless the number is - part of a measurement - </para> - </listitem> - <listitem> + part of a measurement + </para> + </listitem> + <listitem> <para> Approximations - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Extreme values such as <emphasis>million</emphasis>, but - precede the value with a numeral - </para> - </listitem> - <listitem> + precede the value with a numeral + </para> + </listitem> + <listitem> <para> - Any number that begins a sentence - </para> - </listitem> - <listitem> + 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> + example: <literal>two 10 MB files</literal> + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Numerals</term> + <listitem> <para> Use numerals in the following situations: - </para> - <itemizedlist> - <listitem> + </para> + <itemizedlist> + <listitem> <para> The number 10 or greater - </para> - </listitem> - <listitem> - <para> Negative numbers - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> + <para> Negative numbers + </para> + </listitem> + <listitem> <para> Most fractions - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Percentages - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> Decimals - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> - Measurements - </para> - </listitem> - <listitem> + Measurements + </para> + </listitem> + <listitem> <para> Units of time smaller than one second - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> References to bits and bytes - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Parentheses</term> - <listitem> + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Parentheses</term> + <listitem> <para> Use parentheses in the following situations: - </para> - <itemizedlist> - <listitem> + </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> + 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> + </listitem> + </varlistentry> + <varlistentry> + <term>Period</term> + <listitem> <para> Use a period in the following situations: - </para> - <itemizedlist> - <listitem> + </para> + <itemizedlist> + <listitem> <para> To end a sentence - </para> - </listitem> - <listitem> + </para> + </listitem> + <listitem> <para> In file and directory names - </para> - </listitem> - <listitem> + </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> + 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, refer - also to the <citetitle>Chicago Manual of Style</citetitle> - (<ulink - url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) + Use standard American English punctuation rules. In + addition to the specific points of punctuation in this + section, refer also to the <citetitle>Chicago Manual of + Style</citetitle> (<ulink + url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Punctuation in numbers</term> - <listitem> + </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> + 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> + 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>See v. Refer to</term> + <term>See v. Refer to</term> <listitem> <para> When referring a user to another resource, use "refer to" - instead of "see", and "refer also to" instead of "see also". - This differentiates from the - <computeroutput><see></computeroutput> and - <computeroutput><seealso></computeroutput> tags that - are used in indexing. These tags create special links in - the index. To be consistent throughout the document, we - reserve the special words "see" and "see also" for - hyperlinked index references, and use "refer to" and "refer - also to" for non-hyperlinked and non-indexed references. + instead of "see", and "refer also to" instead of "see also". + This differentiates from the <sgmltag + class="starttag">see</sgmltag> and <sgmltag + class="starttag">seealso</sgmltag> tags that are used in + indexing. These tags create special links in the index. To + be consistent throughout the document, we reserve the + special words "see" and "see also" for hyperlinked index + references, and use "refer to" and "refer also to" for + non-hyperlinked and non-indexed references. </para> </listitem> </varlistentry> - <varlistentry> - <term>Semicolon</term> - <listitem> + <varlistentry> + <term>Semicolon</term> + <listitem> <para> - Do not use semicolons. + Do not use semicolons. </para> - </listitem> - </varlistentry> + </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. + slashes "/" in your writing. The construction + <literal>and/or</literal>, for example, does not exist. Use + one or the other term instead. </para> </listitem> </varlistentry> - <varlistentry> - <term>Spelling</term> - <listitem> + <varlistentry> + <term>Spelling</term> + <listitem> <para> Use standard American English spelling rules, refer to the - <citetitle>American Heritage Dictionary</citetitle> (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) - for guidelines. + <citetitle>American Heritage Dictionary</citetitle> (<ulink + url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) + for guidelines. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Titles</term> - <listitem> + </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> + </listitem> + </varlistentry> + <varlistentry> + <term>Units</term> + <listitem> <para> Follow these rules when using units: </para> - <itemizedlist> - <listitem> + <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, refer to the <citetitle>IEEE Standard Dictionary - of Electrical and Electronics Terms</citetitle>. - </para> - </listitem> - <listitem> + 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, refer to 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> + for a word. + </para> + </listitem> + <listitem> <para> Most standard abbreviations of units account for both - singular and plural usage. - </para> - </listitem> - <listitem> + singular and plural usage. + </para> + </listitem> + <listitem> <para> Insert a space between the numeral and the unit of - measurement. - </para> - </listitem> + measurement. + </para> + </listitem> </itemizedlist> - </listitem> - </varlistentry> - </variablelist> + </listitem> + </varlistentry> + </variablelist> </section> @@ -1641,18 +1647,18 @@ <!-- - This section will collect miscellanea and advice for specific situations - that the &FDP; editors encounter. I hope they will feel free to e-mail - me sticky situations or particularly interesting examples of work - they've beautified. Hopefully not too much will be drawn from my own - work! + This section will collect miscellanea and advice for specific + situations that the FDP editors encounter. I hope they will feel + free to e-mail me sticky situations or particularly interesting + examples of work they've beautified. Hopefully not too much will be + drawn from my own work! -- PWF. --> <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 + 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> @@ -1660,15 +1666,15 @@ <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. + tutorial tells the user how to accomplish a task, and should + give instructions clearly and concisely. Avoid using "must," + "need to," and the like. These words are redundant in a + tutorial, since the reader assumes you are outlining necessary + steps to accomplish a task. Also avoid using "maybe," "might," + and other words that indicate you are unsure about the subject + matter. Your tutorial should cover a subject authoritatively. + The reader should never be concerned about unknown effects of + following the tutorial. </para> <example id="ex-misc-passive-voice"> <title>Incorrect: Passive voice</title> @@ -1676,7 +1682,8 @@ The <command>yum update</command> command must be run. </para> <para> - You should run the <command>yum update</command> command. + You might want to run the <command>yum update</command> + command. </para> </example> <example id="ex-misc-active-voice"> @@ -1690,13 +1697,12 @@ <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; refer also to - <xref - linkend="sn-misc-active-voice"/>. + Write in the present tense. A good rule of thumb is that the + words "will" and "shall" are almost never needed in describing + what the user should do or see. They add unnecessary length to + sentences and can confuse translators. They are also often + indicators of passive voice; refer also to <xref + linkend="sn-misc-active-voice"/>. </para> <example id="ex-misc-future-tense"> <title>Incorrect: Future tense</title> @@ -1714,38 +1720,38 @@ </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." + 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. + <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. + 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. + configuring the Samba server. </para> <para> - Users can back up files with the <command>tar</command> or - <command>cpio</command> command. + If necessary, users can back up files with the + <command>tar</command> or <command>cpio</command> command. </para> </example> </section> @@ -1753,12 +1759,12 @@ <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>. Refer to <xref - linkend="vle-contractions" />. + 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>. Refer to <xref + linkend="vle-contractions" />. </para> </section> @@ -1766,12 +1772,12 @@ <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. + 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> @@ -1779,36 +1785,36 @@ <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. + 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. Refer also to <xref linkend="vle-golden-rule-4" />. + Avoid statements such as "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. Refer also to <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. + 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> @@ -1816,7 +1822,7 @@ <listitem> <para> Go to the <guimenu>Main Menu</guimenu> -> - <guimenuitem>Foobar</guimenuitem> + <guimenuitem>Foobar</guimenuitem> </para> </listitem> <listitem> @@ -1832,7 +1838,7 @@ <listitem> <para> From the <guimenu>Main Menu</guimenu>, select - <guimenuitem>Foobar</guimenuitem> + <guimenuitem>Foobar</guimenuitem> </para> </listitem> <listitem> @@ -1846,29 +1852,28 @@ <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. + "click" freely. If you are writing about an application that + has a text-mode interface, use "select" instead as shown + above. </para> </important> </section> - + <section id="sn-misc-docbook-tips"> <title>DocBook Tips</title> <para> This section contains tips on how to use DocBook tags more - effectively in your documentation. + 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. + Avoid overuse of admonitions. Keep admonitions short and + effective by using only the most important material inside the + admonition. Move any background material required to explain + the admonition statements outside the admonition. </para> <example id="ex-misc-ineffective-admonition"> <title>Incorrect: Lengthy admonition</title> @@ -1877,13 +1882,13 @@ <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. + 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> @@ -1891,61 +1896,67 @@ <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. + 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. + 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"). + 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> + <para> + Follow the capitalization rules for headings in the title of + an admonition. + </para> </section> <section id="sn-misc-replaceable"> - <title>The <replaceable> Tag</title> + <title>The <sgmltag class="starttag">replaceable</sgmltag> + 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. + used as a convention, do not use the <sgmltag + class="starttag">replaceable</sgmltag> 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. (Refer also to - <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;." + Use the entities provided by the &FDP;. These entities are + found in the <filename>common/</filename> folder in the + <filename>fedora-docs</filename> distribution. (Refer also to + <xref linkend="ch-getting-files"/>.) For instance, do not use + abbreviations such as "FC2." Instead, use the predefined + entities "&FC; &FCVER;," which produces the text "&FC; + &FCVER;." </para> </section> </section> - + </section> - + </chapter> + <!-- Keep this comment at the end of the file Local variables: mode: xml sgml-parent-document:("documentation-guide-en.xml" "book" "chapter") +fill-column: 72 End: --> - |