From 243baeb660d521f40c5eaab8aa656ac9a6ba9e73 Mon Sep 17 00:00:00 2001 From: Karsten Wade Date: Thu, 28 Apr 2005 08:55:41 +0000 Subject: This represents that state of the Doc Guide with Paul's Style chapter included, prior to _any_ editing from me. --- docs-style-en.xml | 1930 ++++++++++++++++++++++++++++++++++++++++++++ documentation-guide-en.xml | 9 +- 2 files changed, 1936 insertions(+), 3 deletions(-) create mode 100644 docs-style-en.xml diff --git a/docs-style-en.xml b/docs-style-en.xml new file mode 100644 index 0000000..6480e54 --- /dev/null +++ b/docs-style-en.xml @@ -0,0 +1,1930 @@ + + + + + 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 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 + + + + + After you complete the configuration changes above, attach the + USB removable media to your system. Use the + dmesg command to examine the kernel message + log. The message USB device + found indicates that your device was + installed successfully. + + + + The first example is more conversational English, which is not + appropriate for official written documentation. The second + example is more formal, but as a result it is easier to + comprehend, both for native readers and translators. + + + Following style rules and guidelines also makes readers more + comfortable with a set of documents. Consistent style enhances + the professional appearance of documentation, and its perceived + value. On the other hand, lapses in punctuation or poor grammar + negatively affect a reader's reaction to written material. A + reader can feel that an otherwise correct technical document is + lacking in authority, simply because it is poorly + written. Readers feel at ease when they do not have to struggle + to understand an author's use of language. + + + This chapter cannot possibly cover enough material to make every + reader a good writer. Some manuals devoted entirely to writing + style are themselves hundreds of pages long. This chapter + provides enough guidelines for intermediate writers to + understand style usage in technical documentation. + + + If you are not a practiced writer, whether of technical + documentation or otherwise, you may benefit from other style + resources. The following list is far from comprehensive, but + provides a starting point: + + + + + The Elements of Style, by William + Strunk. 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/. + + +
+ +
+ + Fundamental Concepts of Technical Documentation + + + Bibliographic Information + + This section is drawn primarily from the + GDSG. + + + + + + + This chapter provides a brief introduction to writing technical + documentation. + + +
+ 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. + + +
+ +
+ +
+ + 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. + + + + + + + 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. + + + + + + + +
+ +
+ + 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 + + 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 + + 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 + . + + + 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. + + +
+ +
+ 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. + +
+ +
+ 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 . + +
+ +
+ 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. + + +
+ 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. + + + + + + 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. + + + + + + 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. + +
+ +
+ 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;." + +
+ +
+ +
+ + diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml index f2f37ea..eae73bb 100644 --- a/documentation-guide-en.xml +++ b/documentation-guide-en.xml @@ -1,8 +1,9 @@ - - + + %FEDORA-ENTITIES-EN; @@ -24,7 +25,7 @@ - + ]> @@ -73,6 +74,8 @@ &TUTORIAL; + &STYLE; + &CONVERTING; &CVS; -- cgit