![[Note]](./stylesheet-images/note.png) | 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 Fedora documentation. Many of these guidelines are only applicable to English-language usage, refer to the American Heritage Dictionary (http://www.bartleby.com/61/) and the Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.)
- Abbreviations
A shortened form of a word or phrase that takes the place of the full word or phrase, such as
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.
For abbreviations of phrases, such as
i.e.for "in other words" ande.g.for "for example", do not use the abbreviation. Spell out the entire phrase.- 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
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. A user can not be "in" a text editor.
- Articles
Do not use the definite article
theto 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.
- 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. Refer to Section 6.21, “replaceable” for information about using this 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
Command Names 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 an incomplete sentence after a colon
- 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
- Grammar
Use standard American English grammar rules, refer to the Chicago Manual of Style ( http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.)
- 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 fewer 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 (http://www.bartleby.com/61/) for guidance
In spelled-out fractions
In variable names of two or more words, such as
directory-name. Note:filenameis 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 (http://www.bartleby.com/61/), 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, refer also to the Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.)
- 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.
- See v. Refer to
When referring a user to another resource, use "refer to" instead of "see", and "refer also to" instead of "see also". This differentiates from the
<see>and<seealso>tags that are used in indexing. These tags create special links in the index. To be consistent throughout the document, we reserve the special words "see" and "see also" for hyperlinked index references, and use "refer to" and "refer also to" for non-hyperlinked and non-indexed references.- 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, refer to the American Heritage Dictionary (http://www.bartleby.com/61/) 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, refer to 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.