From bd31c100a2ad1ac8f376d8916404fc410fb4e53c Mon Sep 17 00:00:00 2001 From: Karsten Wade Date: Thu, 28 Apr 2005 09:20:15 +0000 Subject: These changes only reflect the inclusion of the local variables and the associate adjusting of indenting. --- docs-style-en.xml | 3632 ++++++++++++++++++++++++++--------------------------- 1 file 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 @@ - + - Style + Style - - Writing good technical documentation is not simply reproducing - command lines and instruction sets. Good documentation is easy to - read, understand, and translate, and presents a concise logical - progression of concepts. Good documentation can also be defined by - what it does not contain. Your tutorial - should avoid: - - - - - excessive wordiness - - - - - unnecessary or undefined jargon - - - - - grammatical or spelling errors - - - - - references to yourself or your experiences - - - - - remarks which might offend or confuse any reader - - - - - 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. - - -
- - Why Style Is Important - + + Writing good technical documentation is not simply reproducing + command lines and instruction sets. Good documentation is easy to + read, understand, and translate, and presents a concise logical + progression of concepts. Good documentation can also be defined by + what it does not contain. Your tutorial should + avoid: + + + + + excessive wordiness + + + - Writing well comes naturally to almost no one. It is a skill - that professional writers, even famous ones, must practice - constantly. Style - style is the quality - that separates elegant writing from the merely functional. + unnecessary or undefined jargon + + - Elegance comes in many forms. In prose and poetry, elegant - writing may not follow some (or any) common rules of grammar, - syntax or spelling. A good example is Episode 18, "Penelope," in - James Joyce's novel Ulysses - - See, e.g. http://www.online-literature.com/james_joyce/ulysses/18/. - Please note that this example contains some mature themes - and language, and is not suitable for all readers. - - . There, Joyce uses long streams of words without - punctuation to simulate a character's internal consciousness. By - violating basic rules of grammar and syntax, Joyce simulates the - disorganized but loosely connected thought patterns of his - narrator. + grammatical or spelling errors + + - 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 - - Incorrect style + + + + remarks which might offend or confuse any reader + + + + + 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. + + +
+ + Why Style Is Important + + + Writing well comes naturally to almost no one. It is a skill that + professional writers, even famous ones, must practice constantly. + Style + style is the quality + that separates elegant writing from the merely functional. + Elegance comes in many forms. In prose and poetry, + elegant writing may not follow some (or any) common rules of + grammar, syntax or spelling. A good example is Episode 18, + "Penelope," in James Joyce's novel + Ulysses + See, e.g. http://www.online-literature.com/james_joyce/ulysses/18/. + Please note that this example contains some mature themes and + language, and is not suitable for all readers. + . There, Joyce uses long streams of words without + punctuation to simulate a character's internal consciousness. By + violating basic rules of grammar and syntax, Joyce simulates the + disorganized but loosely connected thought patterns of his + narrator. + + + Technical documentation, however, should always respect these + rules. The more a document departs from standard language usage, + the more difficult the material becomes for the reader. For + example, readers may not be native speakers of the language used, + or they might be reading a translation. If the writer uses slang, + 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: + + + Incorrect style - - So you made the changes I showed you in the last section. - What's the next thing you should do? Just pop your thumb drive - onto your system and read the messages - log. When you see "USB device found," then Bob's your uncle. - - - - Correct style + + So you made the changes I showed you in the last section. What's + the next thing you should do? Just pop your thumb drive onto + your system and read the messages log. When + you see "USB device found," then Bob's your uncle. + + + + Correct style - - After you complete the configuration changes above, attach the - USB removable media to your system. Use the - dmesg command to examine the kernel message - log. The message USB device - found indicates that your device was - installed successfully. - - - - The first example is more conversational English, which is not - appropriate for official written documentation. The second - example is more formal, but as a result it is easier to - comprehend, both for native readers and translators. - - Following style rules and guidelines also makes readers more - comfortable with a set of documents. Consistent style enhances - the professional appearance of documentation, and its perceived - value. On the other hand, lapses in punctuation or poor grammar - negatively affect a reader's reaction to written material. A - reader can feel that an otherwise correct technical document is - lacking in authority, simply because it is poorly - written. Readers feel at ease when they do not have to struggle - to understand an author's use of language. + After you complete the configuration changes above, attach the + USB removable media to your system. Use the + dmesg command to examine the kernel message + log. The message USB device + found indicates that your device was + installed successfully. - - This chapter cannot possibly cover enough material to make every - reader a good writer. Some manuals devoted entirely to writing - style are themselves hundreds of pages long. This chapter - provides enough guidelines for intermediate writers to - understand style usage in technical documentation. - - - If you are not a practiced writer, whether of technical - documentation or otherwise, you may benefit from other style - resources. The following list is far from comprehensive, but - provides a starting point: - - - - - The Elements of Style, by William - Strunk. Online version: http://bartleby.com/141/ - - + + + The first example is more conversational English, which is not + appropriate for official written documentation. The second example + is more formal, but as a result it is easier to comprehend, both + for native readers and translators. + + + Following style rules and guidelines also makes readers more + comfortable with a set of documents. Consistent style enhances the + professional appearance of documentation, and its perceived value. + On the other hand, lapses in punctuation or poor grammar + negatively affect a reader's reaction to written material. A + reader can feel that an otherwise correct technical document is + lacking in authority, simply because it is poorly written. Readers + feel at ease when they do not have to struggle to understand an + author's use of language. + + + This chapter cannot possibly cover enough material to make every + reader a good writer. Some manuals devoted entirely to writing + style are themselves hundreds of pages long. This chapter provides + enough guidelines for intermediate writers to understand style + usage in technical documentation. + + + If you are not a practiced writer, whether of technical + documentation or otherwise, you may benefit from other style + resources. The following list is far from comprehensive, but + provides a starting point: + + + + + The Elements of Style, by William + Strunk. Online version: http://bartleby.com/141/ + + - - - The Chicago Manual of Style, by the - University of Chicago Press. Online version: http://www.chicagomanualofstyle.org/ - - - - - Paradigm Online Writing Assistant, - maintained by Chuck Guilford, Ph.D. Online only: http://www.powa.org/ - - - - - There are many free software documentation projects which have - developed their own style guidelines. This chapter, in fact, - draws heavily on the GNOME Documentation Style - Guidelines (GDSG). You may - read the original GDSG at http://developer.gnome.org/documents/style-guide/. - + + + The Chicago Manual of Style, by the + University of Chicago Press. Online version: http://www.chicagomanualofstyle.org/ + + + + + Paradigm Online Writing Assistant, + maintained by Chuck Guilford, Ph.D. Online only: http://www.powa.org/ + + + + + There are many free software documentation projects which have + developed their own style guidelines. This chapter, in fact, draws + heavily on the GNOME Documentation Style + Guidelines (GDSG). You may + read the original GDSG at http://developer.gnome.org/documents/style-guide/. + -
+
-
+
- Fundamental Concepts of Technical Documentation + Fundamental Concepts of Technical Documentation - - Bibliographic Information - - This section is drawn primarily from the - GDSG. - - + + Bibliographic Information + + This section is drawn primarily from the + GDSG. + + + + This chapter provides a brief introduction to writing technical + documentation. + + +
+ General Style Requirements - This chapter provides a brief introduction to writing technical - documentation. + Technical writing for the &FP; imposes special constraints + beyond the basic requirements of good prose. Good &FED; + technical documentation has the following characteristics: + + + Comprehensive + + + Describe all of the functionality of a product. Do not + omit functionality that you regard as irrelevant for the + user. + + + + + Conformant + + + Describe what you see. Do not describe what you want to + see. Present your information in the order that users + experience the subject matter. + + + + + Clear + + + Read The + Elements of Style to help make + your writing clear. + + + + + Consistent + + + Use agreed vocabulary throughout your documentation. Use + the same vocabulary as other writers who are working on + related documentation. + + + + + Concise + + + Review your work frequently as you write your document. Ask + yourself which words you can take out. See for a specific guideline. + + + + +
+
+ Golden Rules + + This section contains some basic style guidelines. Subsequent + sections in this chapter expand on these guidelines to give more + detailed guidance. + + + + Golden Rule 1: Be brief. + + + + + Limit each sentence to less than 25 words. + + + + + Limit each procedure step to 23 words. + + + + + Incorrect: Too long + 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. + + + + Correct: Less wordy + + Normally, the kernel stores the data in memory prior to + periodically writing the data to the disk. + + + + + + Golden Rule 2: Be organized. + + + + + Limit each paragraph to one topic. + + + + + Limit each sentence to one idea. + + + + + Limit each procedure step to one action. + + + + + Incorrect: Disorganized topics + + The Workspace Switcher applet + helps you navigate all of the virtual desktops available + on your system. The X Window system, working in hand + with a piece of software called a window + manager, allows you to create more than one + virtual desktop, known as + workspaces, to organize your work, + with different applications running in each workspace. + The Workspace Switcher applet + is a navigational tool to get around the various + workspaces, providing a miniature road map in the GNOME + panel showing all your workspaces and allowing you to + switch easily between them. + + + + Correct: Organized topics + + You can use the Workspace + Switcher to add new + workspaces to the GNOME Desktop. + You can run different applications in each workspace. + The Workspace Switcher applet + provides a miniature map that shows all of your + workspaces. You can use the Workspace + Switcher applet to switch between + workspaces. + + + + + Plan the order of paragraphs before you start writing. + Decide which topic you want to cover in each paragraph. + + + + + + Golden Rule 3: Be demonstrative. + + + Use explicit examples to demonstrate how an application + works. Provide instructions rather than descriptions. + + + Incorrect: Describes but does not + demonstrate + + There is a text box that you can use to find out the + definition of a word. + + + + Correct: Demonstrates usage + + To request a definition of a word, type the word in the + text box, then click on the Lookup button. + + + + + Do not apply this guideline too rigidly. Sometimes you + must explain how software works to support your how-to + examples. + + + + + + Golden Rule 4: Be objective. + + + Write in a neutral tone. + + + Incorrect: Sentence takes sides + + The applet is a handy little screen grabber. + + + + Correct: Sentence is objective + + Use the applet to take screenshots. + + + + + -
- General Style Requirements - - Technical writing for the &FP; imposes special constraints - beyond the basic requirements of good prose. Good &FED; - technical documentation has the following characteristics: - - - - Comprehensive - - - Describe all of the functionality of a product. Do not - omit functionality that you regard as irrelevant for the - user. - - - - - Conformant - - - Describe what you see. Do not describe what you want to - see. Present your information in the order that users - experience the subject matter. - - - - - Clear - - - Read The - Elements of Style to help make - your writing clear. - - - - - Consistent - - - Use agreed vocabulary throughout your documentation. Use - the same vocabulary as other writers who are working on - related documentation. - - - - - Concise - - - Review your work frequently as you write your document. - Ask yourself which words you can take out. See for a specific - guideline. - - - - -
-
- Golden Rules - - This section contains some basic style guidelines. Subsequent - sections in this chapter expand on these guidelines to give - more detailed guidance. - - - - Golden Rule 1: Be brief. - - - - - Limit each sentence to less than 25 words. - - - - - Limit each procedure step to 23 words. - - - - - Incorrect: Too long - - 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. - - - - Correct: Less wordy - - Normally, the kernel stores the data in memory prior - to periodically writing the data to the disk. - - - - - - Golden Rule 2: Be organized. - - - - - Limit each paragraph to one topic. - - - - - Limit each sentence to one idea. - - - - - Limit each procedure step to one action. - - - - - Incorrect: Disorganized topics - - The Workspace Switcher - applet helps you navigate all of the virtual desktops - available on your system. The X Window system, working - in hand with a piece of software called a - window manager, allows you to - create more than one virtual desktop, known as - workspaces, to organize your - work, with different applications running in each - workspace. The Workspace - Switcher applet is a navigational tool - to get around the various workspaces, providing a - miniature road map in the GNOME panel showing all your - workspaces and allowing you to switch easily between - them. - - - - Correct: Organized topics - - You can use the Workspace - Switcher to add new - workspaces to the GNOME Desktop. - You can run different applications in each workspace. - The Workspace Switcher - applet provides a miniature map that shows all of your - workspaces. You can use the Workspace - Switcher applet to switch between - workspaces. - - - - - Plan the order of paragraphs before you start writing. - Decide which topic you want to cover in each - paragraph. - - - - - - Golden Rule 3: Be demonstrative. - - - Use explicit examples to demonstrate how an application - works. Provide instructions rather than descriptions. - - - Incorrect: Describes but does not - demonstrate - - There is a text box that you can use to find out the - definition of a word. - - - - Correct: Demonstrates usage - - To request a definition of a word, type the word in - the text box, then click on the Lookup button. - - - - - Do not apply this guideline too rigidly. Sometimes you - must explain how software works to support your how-to - examples. - - - - - - Golden Rule 4: Be objective. - - - Write in a neutral tone. - - - Incorrect: Sentence takes sides - - The applet is a handy little screen grabber. - - - - Correct: Sentence is objective - - Use the applet to take screenshots. - - - - - - -
- -
+
- Tone - - 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: - - - - Avoid humor - - - Humor distracts from the information you are trying to - provide. Humor also makes documentation difficult to - translate. Stay factual. - - - - - Avoid personal opinions - - - Whether you think a function is useful or woeful is - irrelevant. Report the function to the user, with - instructions about how to use the function. Stay - accurate. - - - - - Avoid colloquial language - - - Colloquial language is difficult to translate and - usually culture-specific. Stay neutral. - - - - - Avoid topical expressions - - - An expression that is in common use today might convey - something completely different tomorrow. Stay technical. - - - - - Avoid aspirational statements - - - Statements about the future developments of a product do - not belong in technical documentation. Write about what - you see right now. Stay real. - - - - -
-
- Reaching the Right Audience - - 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. - -
-
- User Motivation - - Do not waste the time of the user who looks for information in - your documentation. Users do not read technical documentation - for entertainment. Users usually have specific questions. You - need to give clear answers to those questions. - -
-
- New Users - - 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. - -
-
- Experienced Users - - 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. - -
-
- Do Not Offend Your Audience - - To avoid offending your readers, apply the following - guidelines to your documentation: - - - - Avoid insider language - - - Insider language includes both undefined jargon and the - tendency of the computer community to shorten words. For - example, use the term documentation - instead of the term docs. You can - identify jargon if terminology fails the following - conditions: - - - - - A term does not appear in the &FED; Jargon Guide. - - - - - A term does not appear in the - American Heritage - Dictionary. - - - - - A term does not appear in the glossary of the manual - that you are writing. - - - - - A term is not defined in the body text of the manual - that you are writing. - - - - - - - Avoid gender-specific language - - - Pronoun constructions such as - his/her or - s/he do not exist. There is no need - to identify gender in your instructions. - - - - - Avoid culture-specific language - - - There is little point in giving an example that everyone - in your town knows about, but is a complete mystery to - everyone else in the world. - - - - - Avoid talking down to your reader - - - There are few experiences more irritating for a user - than documentation that says an action is easy or quick, - when in fact the user cannot complete the action. Do not - qualify or prejudge actions. - - - - - - Other parts of this guide discuss in more detail tone and - language usage that can cause offense. - +
-
+ Tone + + 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: + + + + Avoid humor + + + Humor distracts from the information you are trying to + provide. Humor also makes documentation difficult to + translate. Stay factual. + + + + + Avoid personal opinions + + + Whether you think a function is useful or woeful is + irrelevant. Report the function to the user, with + instructions about how to use the function. Stay accurate. + + + + + Avoid colloquial language + + + Colloquial language is difficult to translate and usually + culture-specific. Stay neutral. + + + + + Avoid topical expressions + + + An expression that is in common use today might convey + something completely different tomorrow. Stay technical. + + + + + Avoid aspirational statements + + + Statements about the future developments of a product do + not belong in technical documentation. Write about what + you see right now. Stay real. + + + + +
+
+ Reaching the Right Audience + + 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. + +
+
+ User Motivation + + Do not waste the time of the user who looks for information in + your documentation. Users do not read technical documentation + for entertainment. Users usually have specific questions. You + need to give clear answers to those questions. + +
+
+ New Users + + 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. + +
+
+ Experienced Users + + 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. + +
+
+ Do Not Offend Your Audience + + To avoid offending your readers, apply the following guidelines + to your documentation: + + + + Avoid insider language + + + Insider language includes both undefined jargon and the + tendency of the computer community to shorten words. For + example, use the term documentation + instead of the term docs. You can + identify jargon if terminology fails the following + conditions: + + + + + A term does not appear in the &FED; Jargon Guide. + + + + + A term does not appear in the + American Heritage + Dictionary. + + + + + A term does not appear in the glossary of the manual + that you are writing. + + + + + A term is not defined in the body text of the manual + that you are writing. + + + + + + + Avoid gender-specific language + + + Pronoun constructions such as his/her + or s/he do not exist. There is no + need to identify gender in your instructions. + + + + + Avoid culture-specific language + + + There is little point in giving an example that everyone + in your town knows about, but is a complete mystery to + everyone else in the world. + + + + + Avoid talking down to your reader + + + There are few experiences more irritating for a user than + documentation that says an action is easy or quick, when + in fact the user cannot complete the action. Do not + qualify or prejudge actions. + + + + + + Other parts of this guide discuss in more detail tone and + language usage that can cause offense. +
-
+
+ +
- Grammar and Usage Guidelines + Grammar and Usage Guidelines - - Bibliographical Information - - This section is drawn partly from the GDSG, and - partly from The Elements of Style, updated as - necessary for the needs of 21st-century technical documentation - writers. - - + + Bibliographical Information + + This section is drawn partly from the + GDSG, and partly from The + Elements of Style, updated as necessary for the + needs of 21st-century technical documentation writers. + + - - This section contains an alphabetical list of grammar and usage - guidelines for use in &FED; documentation. Many of these guidelines are - only applicable to English-language usage, see the American Heritage - Dictionary and the - Chicago Manual of Style. - - - - Abbreviations - - - 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: - - - - - Avoid creating new abbreviations. Unfamiliar - abbreviations can confuse rather than clarify a - concept. - - - - - Do not explain or expand familiar abbreviations. - - - - - Do not include familiar abbreviations in the glossary - of your manual. - - - - - - - Adjectives - - - Use adjectives with caution. If an adjective is necessary - to differentiate between items, then use adjectives. In - all cases, test whether the phrase can stand alone without - the adjective. - - - - - Acronyms - - - A term that represents a multi-word term. Typically, - acronyms are formed in the following ways: - - - - - From the first letters of each word in a compound - term, for example Table of Contents (TOC). - - - - - From recognizable parts of a compound term, such as - GNU Object Model Environment (GNOME). - - - - - Apply the following rules when you use acronyms: - - - - - On the first occurrence of an acronym, spell out the - full term, with the acronym in parentheses. - - - - - Do not spell out the full compound for well-known - acronyms, unless you think the information is useful - for readers. - - - - - Avoid creating new acronyms. Unfamiliar acronyms can - confuse rather than clarify a concept. - - - - - Write the acronym in uppercase letters, unless there - is a compelling case for lowercase. - - - - - Include the acronym and the full term in the glossary - of your manual. - - - - - - - Adverbs - - - Use adverbs with caution. If an adverb is necessary to - qualify the function of a component, then use an adverb. - In all cases, test whether the phrase can stand alone - without the adverb. Classic superfluous adverbs are: - simply, easily, quickly. - - - - - Anthropomorphism - - - - - Do not apply emotions, desires, or opinions to - software applications. - - - - - Do not apply a sense of location or dimension to a - software application. You can not be - in a text editor. - - - - - - - Articles - - - Do not use the definite article the - to begin any of the following items: - - - - - Manual titles - - - - - Chapter titles - - - - - Headings - - - - - Figure captions - - - - - Table captions - - - - - Callouts - - - - - - - Apostrophe - - - Do not use apostrophes except where absolutely - required - - - - - Do not use apostrophes to denote possession. - - - - - Do not use apostrophes to denote contractions. - - - - - Do not use apostrophes to denote plurals. - - - - - Incorrect: Apostrophes - - - - the Main Menu's - Help option - - - - - don't use the default option - - - - - several SCSI disk's - - - - - - Correct: No apostrophes - - - - the Help option on the - Main Menu - - - - - do not use the default option - - - - - several SCSI disks - - - - - - - - Brackets - - - - - Do not use brackets [such as these] as a substitute - for parentheses (such as these). - - - - - Use brackets for optional command line entries. - - - - - Do not use angle brackets to indicate variables in - text, instead use the replaceable - tag. - - - - - - - Capitalization - - - Capitalize in the following situations: - - - - - All letters in acronyms, unless the acronym is a - well-known exception - - - - - Initial letter of the first word in a list - - - - - Initial letter of the first word in a callout - - - - - Initial letter of a key name, such as the - Shift key - - - - - Initial letter of a sentence. Avoid starting a - sentence with a command name or application name that - has a lowercase initial letter - - - - - Initial letter of a complete sentence after a colon - - - - - Do not capitalize in the following situations: - - - - - A compound term that is followed by an abbreviation or - an acronym - - - - - When you want to emphasize something - - - - - Variable names - - - - - The initial letter of the first word following a - colon, if the word is part of an incomplete sentence - - - - - - - Captions - - - Use the same rules as for headings, for all captions - accompanying figures and tables. Do not put a period at - the end of a caption. - - - - - Colon - - - Use a colon in the following situations: - - - - - To introduce a list - - - - - Before an explanation - - - - - After an introduction - - - - - Do not use a colon in the following situations: - - - - - To introduce a figure or a table - - - - - To introduce headings - - - - - At the end of an introduction to a procedure - - - - - - - Column headings - - - Use the same rules as for headings. - - - - - Comma - - - Use commas in the following situations: - - - - - To separate items in a series - - - - - To separate the parts of a sentence - - - - - To separate nonrestrictive phrases - - - - - Instead of dashes to set off appositives - - - - - With for example and similar - expressions - - - - - Do not use commas in the following situations: - - - - - In a series of adjectives used as one modifier - - - - - Between two short independent clauses - - - - - - - Commands - - - Do not use commands as verbs. - - - - - Contractions - - - Do not use contractions such as - can't, don't, or - isn't. - - - - - Dash - - - Do not use the em dash or the en dash. Use a paragraph - break or a colon instead, where you want to create an - introductory piece of text. If you have several items that - you want to introduce, then you can use a variable list. - - - - - Ellipsis - - - Use an ellipsis in the following situations: - - - - - To show that you have omitted something from a - sentence - - - - - To indicate a pause when you quote displayed text - - - - - - - Fractions - - - Follow these rules when using fractions: - - - - - Use numerals for fractions in tables and in units of - measurement, but spell out fractions in prose. - - - - - Use a space between a numeral and a related fraction, - if there is a possible ambiguity. For example: 1 - 1/2 instead of 11/2. - - - - - If a fraction is used in a compound modifier, insert a - hyphen between the fraction and the unit of - measurement. - - - - - - - Gender - - - See . - - - - - Grammar - - - Use standard American English grammar rules, see the - - Chicago Manual of Style. - - - - - Headings - - - Use the following capitalization rules in headings: - - - - - Initial uppercase letter of the first word - - - - - Initial uppercase letter for all nouns, adjectives, - and verbs. - - - - - All lowercase letters for conjunctions, articles, and - prepositions of less than four letters - - - - - Initial uppercase letter for prepositions of four - letters or longer - - - - - Initial uppercase letter for conjunctions of four - letters or longer - - - + + 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 + American + Heritage Dictionary and the + Chicago Manual of Style. + + + + Abbreviations + + + 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: + + + + + Avoid creating new abbreviations. Unfamiliar + abbreviations can confuse rather than clarify a concept. + + + + + Do not explain or expand familiar abbreviations. + + + + + Do not include familiar abbreviations in the glossary of + your manual. + + + + + + + Adjectives + + + Use adjectives with caution. If an adjective is necessary to + differentiate between items, then use adjectives. In all + cases, test whether the phrase can stand alone without the + adjective. + + + + + Acronyms + + + A term that represents a multi-word term. Typically, + acronyms are formed in the following ways: + + + + + From the first letters of each word in a compound term, + for example Table of Contents (TOC). + + + + + From recognizable parts of a compound term, such as GNU + Object Model Environment (GNOME). + + + + + Apply the following rules when you use acronyms: + + + + + On the first occurrence of an acronym, spell out the + full term, with the acronym in parentheses. + + + + + Do not spell out the full compound for well-known + acronyms, unless you think the information is useful for + readers. + + + + + Avoid creating new acronyms. Unfamiliar acronyms can + confuse rather than clarify a concept. + + + + + Write the acronym in uppercase letters, unless there is + a compelling case for lowercase. + + + + + Include the acronym and the full term in the glossary of + your manual. + + + + + + + Adverbs + + + Use adverbs with caution. If an adverb is necessary to + qualify the function of a component, then use an adverb. In + all cases, test whether the phrase can stand alone without + the adverb. Classic superfluous adverbs are: + simply, easily, quickly. + + + + + Anthropomorphism + + + + + Do not apply emotions, desires, or opinions to software + applications. + + + + + Do not apply a sense of location or dimension to a + software application. You can not be + in a text editor. + + + + + + + Articles + + + Do not use the definite article the to + begin any of the following items: + + + + + Manual titles + + + + + Chapter titles + + + + + Headings + + + + + Figure captions + + + + + Table captions + + + + + Callouts + + + + + + + Apostrophe + + + Do not use apostrophes except where absolutely required + + + + + Do not use apostrophes to denote possession. + + + + + Do not use apostrophes to denote contractions. + + + + + Do not use apostrophes to denote plurals. + + + + + Incorrect: Apostrophes + + + + the Main Menu's + Help option + + + + + don't use the default option + + + + + several SCSI disk's + + + + + + Correct: No apostrophes + + + + the Help option on the + Main Menu + + + + + do not use the default option + + + + + several SCSI disks + + + + + + + + Brackets + + + + + Do not use brackets [such as these] as a substitute for + parentheses (such as these). + + + + + Use brackets for optional command line entries. + + + + + Do not use angle brackets to indicate variables in text, + instead use the replaceable tag. + + + + + + + Capitalization + + + Capitalize in the following situations: + + + + + All letters in acronyms, unless the acronym is a + well-known exception + + + + + Initial letter of the first word in a list + + + + + Initial letter of the first word in a callout + + + + + Initial letter of a key name, such as the + Shift key + + + + + Initial letter of a sentence. Avoid starting a sentence + with a command name or application name that has a + lowercase initial letter + + + + + Initial letter of a complete sentence after a colon + + + + + Do not capitalize in the following situations: + + + + + A compound term that is followed by an abbreviation or + an acronym + + + + + When you want to emphasize something + + + + + Variable names + + + + + The initial letter of the first word following a colon, + if the word is part of an incomplete sentence + + + + + + + Captions + + + Use the same rules as for headings, for all captions + accompanying figures and tables. Do not put a period at the + end of a caption. + + + + + Colon + + + Use a colon in the following situations: + + + + + To introduce a list + + + + + Before an explanation + + + + + After an introduction + + + + + Do not use a colon in the following situations: + + + + + To introduce a figure or a table + + + + + To introduce headings + + + + + At the end of an introduction to a procedure + + + + + + + Column headings + + + Use the same rules as for headings. + + + + + Comma + + + Use commas in the following situations: + + + + + To separate items in a series + + + + + To separate the parts of a sentence + + + + + To separate nonrestrictive phrases + + + + + Instead of dashes to set off appositives + + + + + With for example and similar + expressions + + + + + Do not use commas in the following situations: + + + + + In a series of adjectives used as one modifier + + + + + Between two short independent clauses + + + + + + + Commands + + + Do not use commands as verbs. + + + + + Contractions + + + Do not use contractions such as can't, + don't, or isn't. + + + + + Dash + + + Do not use the em dash or the en dash. Use a paragraph break + or a colon instead, where you want to create an introductory + piece of text. If you have several items that you want to + introduce, then you can use a variable list. + + + + + Ellipsis + + + Use an ellipsis in the following situations: + + + + + To show that you have omitted something from a sentence + + + + + To indicate a pause when you quote displayed text + + + + + + + Fractions + + + Follow these rules when using fractions: + + + + + Use numerals for fractions in tables and in units of + measurement, but spell out fractions in prose. + + + + + Use a space between a numeral and a related fraction, if + there is a possible ambiguity. For example: 1 1/2 + instead of 11/2. + + + + + If a fraction is used in a compound modifier, insert a + hyphen between the fraction and the unit of measurement. + + + + + + + Gender + + See . + + + + + Grammar + + + Use standard American English grammar rules, see the + Chicago Manual of Style. + + + + + Headings + + + Use the following capitalization rules in headings: + + + + + Initial uppercase letter of the first word + + + + + Initial uppercase letter for all nouns, adjectives, and + verbs. + + + + + All lowercase letters for conjunctions, articles, and + prepositions of less than four letters + + + + + Initial uppercase letter for prepositions of four + letters or longer + + + + + Initial uppercase letter for conjunctions of four + letters or longer + + + - - - - Hyphen - - - Use hyphens in the following situations: - - - - - With a numeral in a compound modifier - - - - - To prevent ambiguity - - - - - With some standard prefixes and suffixes. Use the - - American Heritage - Dictionary for guidance - - - - - In spelled-out fractions - - - - - In variable names of two or more words, such as - directory-name. Note: - filename is an exception. - - - - - Do not use hyphens in the following situations: - - - - - For industry-accepted terms - - - - - To construct verbs - - - - - With an adverb ending in ly - - - - - With numerals as single modifiers - - - - - With a word that is listed as unhyphenated in the - - American Heritage - Dictionary, and that uses a - common prefix - - - - - With trademarked terms - - - - - - - Latin terms - - - Do not use Latin terms. Use an equivalent English term - instead. - - - - - Like - - - Do not use the term like to - denote equivalence or similarity. - - - - - Lists - - - Introduce a list with a complete sentence that ends with a - colon. - - - - - Numbers - - - Spell out numbers in the following situations: - - - - - Numbers from zero through nine unless the number - is part of a measurement - - - - - Approximations - - - - - Extreme values such as million, - but precede the value with a numeral - - - - - Any number that begins a sentence - - - - - A number that is immediately followed by a numeral, - for example: two 10 MB files - - - - - - - Numerals - - - Use numerals in the following situations: - - - - - The number 10 or greater - - - - - Negative numbers - - - - - Most fractions - - - - - Percentages - - - - - Decimals - - - - - Measurements - - - - - Units of time smaller than one second - - - - - References to bits and bytes - - - - - - - Parentheses - - - Use parentheses in the following situations: - - - - - To contain the abbreviation of a term on the first - occurrence of the full term - - - - - In man page references, specifically the section - number - - - - - - - Period - - - Use a period in the following situations: - - - - - To end a sentence - - - - - In file and directory names - - - - - In abbreviations that can be mistaken for words, such - as a.m. and U.S. - - - - - - - Punctuation - - - Use standard American English punctuation rules. In - addition to the specific points of punctuation in this - section, see also the - Chicago Manual of Style. - - - - - Punctuation in numbers - - - Do not use a comma in numerals of four digits. Use a comma - in numerals of more than four digits. - - - - - Quotation marks - - - Use quotation marks to indicate material that is taken - verbatim from another source. Do not use quotation marks - to excuse terms from legitimacy. If the term is not - legitimate, then use another term. If you must use that - term, declare the term in the glossary and make the term - legitimate. - - - - - Semicolon - - - Do not use semicolons. - - - - - Slash - - - Except where required as part of a filename, do not use - slashes "/" in your writing. The construction - "and/or," for example, does not exist. Use one or the - other term instead. - - - - - Spelling - - - Use standard American English spelling rules, see the - - American Heritage - Dictionary for guidelines. - - - - - Titles - - - For manual titles use the same rules as for headings. - - - - - Units - - - Follow these rules when using units: - - - - - Use standard abbreviations for units of measurements, - do not invent your own abbreviations. - - - - For further - guidelines, see the IEEE Standard - Dictionary of Electrical and Electronics - Terms. - - - - - Use periods for abbreviated units that might be - mistaken for a word. - - - - - Most standard abbreviations of units account for both - singular and plural usage. - - - - - Insert a space between the numeral and the unit of - measurement. - - - - - - + + + + Hyphen + + + Use hyphens in the following situations: + + + + With a numeral in a compound modifier + + + + + To prevent ambiguity + + + + + With some standard prefixes and suffixes. Use the American + Heritage Dictionary for guidance + + + + + In spelled-out fractions + + + + + In variable names of two or more words, such as + directory-name. Note: + filename is an exception. + + + + + Do not use hyphens in the following situations: + + + + + For industry-accepted terms + + + + + To construct verbs + + + + + With an adverb ending in ly + + + + + With numerals as single modifiers + + + + + With a word that is listed as unhyphenated in the American + Heritage Dictionary, and that + uses a common prefix + + + + + With trademarked terms + + + + + + + Latin terms + + + Do not use Latin terms. Use an equivalent English term + instead. + + + + + Like + + + Do not use the term like to denote + equivalence or similarity. + + + + + Lists + + + Introduce a list with a complete sentence that ends with a + colon. + + + + + Numbers + + + Spell out numbers in the following situations: + + + + Numbers from zero through nine unless the number is + part of a measurement + + + + + Approximations + + + + + Extreme values such as million, but + precede the value with a numeral + + + + + Any number that begins a sentence + + + + + A number that is immediately followed by a numeral, for + example: two 10 MB files + + + + + + + Numerals + + + Use numerals in the following situations: + + + + + The number 10 or greater + + + + Negative numbers + + + + + Most fractions + + + + + Percentages + + + + + Decimals + + + + + Measurements + + + + + Units of time smaller than one second + + + + + References to bits and bytes + + + + + + + Parentheses + + + Use parentheses in the following situations: + + + + + To contain the abbreviation of a term on the first + occurrence of the full term + + + + In man page references, specifically the section + number + + + + + + + Period + + + Use a period in the following situations: + + + + + To end a sentence + + + + + In file and directory names + + + + + In abbreviations that can be mistaken for words, such as + a.m. and U.S. + + + + + + + Punctuation + + + Use standard American English punctuation rules. In addition + to the specific points of punctuation in this section, see + also the + Chicago Manual of Style. + + + + + Punctuation in numbers + + + Do not use a comma in numerals of four digits. Use a comma + in numerals of more than four digits. + + + + + Quotation marks + + + Use quotation marks to indicate material that is taken + verbatim from another source. Do not use quotation marks to + excuse terms from legitimacy. If the term is not legitimate, + then use another term. If you must use that term, declare + the term in the glossary and make the term legitimate. + + + + + Semicolon + + + Do not use semicolons. + + + + + Slash + + + Except where required as part of a filename, do not use + slashes "/" in your writing. The construction + "and/or," for example, does not exist. Use one or the + other term instead. + + + + + Spelling + + + Use standard American English spelling rules, see the American + Heritage Dictionary for guidelines. + + + + + Titles + + + For manual titles use the same rules as for headings. + + + + + Units + + + Follow these rules when using units: + + + + + Use standard abbreviations for units of measurements, do + not invent your own abbreviations. + + + + For further + guidelines, see the IEEE Standard Dictionary + of Electrical and Electronics Terms. + + + + + Use periods for abbreviated units that might be mistaken + for a word. + + + + + Most standard abbreviations of units account for both + singular and plural usage. + + + + + Insert a space between the numeral and the unit of + measurement. + + + + + + -
+
-
+
- Composition Tips + Composition Tips + + 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. + + +
+ Active Voice - 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. + + Incorrect: Passive voice + + The yum update command must be run. + + + You should run the yum update command. + + + + Correct: Active voice + + Run the yum update command. + + +
-
- Active Voice - - 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. - - - Incorrect: Passive voice - - The yum update command must be run. - - - You should run the yum update command. - - - - Correct: Active voice - - Run the yum update command. - - -
- -
- Present Tense - +
+ Present Tense + 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 . - - - Incorrect: Future tense - - The application will display a list of target files. - - - A list of target files will be displayed by the application. - - - - Correct: Present tense - - The application displays a list of target files. - - -
+ + + Incorrect: Future tense + + The application will display a list of target files. + + + A list of target files will be displayed by the application. + + + + Correct: Present tense + + The application displays a list of target files. + + +
-
- Narrative Voice - - 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." - - - Incorrect: First or third person - - As described in the last section, I always run - up2date before configuring the Samba - server. - - - If the user needs to back up his or her files, s/he should - use the tar or cpio - command. - - - - Correct: Second (or no) person - - Refer to the section on up2date before - configuring the Samba server. - - - Users can back up files with the tar or - cpio command. - - -
+
+ Narrative Voice + + 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." + + + Incorrect: First or third person + + As described in the last section, I always run + up2date before configuring the Samba + server. + + + If the user needs to back up his or her files, s/he should use + the tar or cpio command. + + + + Correct: Second (or no) person + + Refer to the section on up2date before + configuring the Samba server. + + + Users can back up files with the tar or + cpio command. + + +
-
- Negative Words - - Avoid negative words when possible, since they give - documentation an overly dogmatic tone. The word "avoid" is - useful for this purpose. Note that contractions are often - used for negative words such as don't or - can't. See + Negative Words + + Avoid negative words when possible, since they give documentation + an overly dogmatic tone. The word "avoid" is useful for this + purpose. Note that contractions are often used for negative + words such as don't or + can't. See . - -
+ +
-
- Uncertainty - - 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. - -
+
+ Uncertainty + + 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. + +
-
- Redundant Coverage - - 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. - -
+
+ Redundant Coverage + + 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. + +
-
- Self-referential Value Judgments - - Avoid statements like "One of the most important things to do - is XYZ." If the procedure is - important, the reader already expects it to be in your - tutorial. The converse is also true: if a procedure appears in - your tutorial, the reader expects it is important. This is - especially true if you use a whole section for the procedure - in question. Merely state, "Do - XYZ." Then elaborate as required. - If the whole section concerns how to do - XYZ, leave this sentence out - entirely. See also . - -
+
+ Self-referential Value Judgments + + Avoid statements like "One of the most important things to do is + XYZ." If the procedure is important, + the reader already expects it to be in your tutorial. The + converse is also true: if a procedure appears in your tutorial, + the reader expects it is important. This is especially true if + you use a whole section for the procedure in question. Merely + state, "Do XYZ." Then elaborate as + required. If the whole section concerns how to do + XYZ, leave this sentence out + entirely. See also . + +
-
- Precision of Language - - Use precise words for actions users should take. Do not - instruct users to "go" to a selection, or "find" a menu. - - - Incorrect: Imprecise wording - - - - Go to the Main Menu -> - Foobar - - - - - Find the option labeled Search - - - - - - Correct: Precise wording - - - - From the Main Menu, select - Foobar - - - - - Select the Search option - - - - - - Do Not Discriminate Against Non-GUI Users - - 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. - - +
+ Precision of Language + + Use precise words for actions users should take. Do not instruct + users to "go" to a selection, or "find" a menu. + + + Incorrect: Imprecise wording + + + + Go to the Main Menu -> + Foobar + + + + + Find the option labeled Search + + + + + + Correct: Precise wording + + + + From the Main Menu, select + Foobar + + + + + Select the Search option + + + + + + Do Not Discriminate Against Non-GUI Users + + 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. + + -
+
-
- DocBook Tips - - This section contains tips on how to use DocBook tags more - effectively in your documentation. - +
+ DocBook Tips + + This section contains tips on how to use DocBook tags more + effectively in your documentation. + -
- Admonitions - - 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. - - - Incorrect: Lengthy admonition - +
+ Admonitions + + 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. + + + Incorrect: Lengthy admonition + - Using <command>sfdisk</command> - - The sfdisk command accepts a script - file as standard input to set up partitions on a hard - disk. Sometimes sfdisk will simply - reject an erroneous input file. In other cases, it - will use the input verbatim, writing an incorrect - partition table to your disk. Always use the - sfdisk -n command to check your - input file before writing to the disk. - + Using <command>sfdisk</command> + + The sfdisk command accepts a script + file as standard input to set up partitions on a hard + disk. Sometimes sfdisk will simply + reject an erroneous input file. In other cases, it will + use the input verbatim, writing an incorrect partition + table to your disk. Always use the sfdisk + -n command to check your input file before + writing to the disk. + - - - - Correct: Brief admonition - - The sfdisk command accepts a script - file as standard input to set up partitions on a hard - disk. Sometimes sfdisk will simply - reject an erroneous input file. In other cases, it will - use the input verbatim, writing an incorrect partition - table to your disk. + + + + Correct: Brief admonition + + The sfdisk command accepts a script file + as standard input to set up partitions on a hard disk. + Sometimes sfdisk will simply reject an + erroneous input file. In other cases, it will use the input + verbatim, writing an incorrect partition table to your disk. - Using <command>sfdisk</command> - - Always use the sfdisk -n command to - check your input file before writing to the disk. - + Using <command>sfdisk</command> + + Always use the sfdisk -n command to + check your input file before writing to the disk. + - - - - Avoid punctuation in titles for sections or admonitions, - except for commas only where demanded. Use a title that says - something about the admonition comment, such as "Reboot - required," instead of simply using the admonition type for a - title ("Note"). - -
+ + + + 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"). + +
-
- The <replaceable> Tag - - 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. - -
+
+ The <replaceable> Tag + + 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. + +
-
- XML Entities - - Use the entities provided by the &FDP;. These entities are - found in the common/ folder in the - fedora-docs distribution. (See also +
+ XML Entities + + Use the entities provided by the &FDP;. These entities are found + in the common/ folder in the + fedora-docs distribution. (See also .) For instance, do not use - abbreviations such as "FC2." Instead, use the predefined - entities "&FC; &FCVER;," which produces the text - "&FC; &FCVER;." - -
- + abbreviations such as "FC2." Instead, use the predefined + entities "&FC; &FCVER;," which produces the text "&FC; + &FCVER;." +
- +
+ +
- + + -- cgit