Archive:DocsProject/StyleGuide/FullGuide

The Fedora Documentation Style Guide

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Introduction to Style

Writing high-quality documents easily understood by multiple readers is a difficult challenge. There are many different techniques that can be used in writing, and there are many different ways of writing the same information. In order to provide consistent, readable documentation, certain standards must be established. There are many different writing style guides that serve different purposes and audiences. Good style is something learned and practiced.

The Fedora Documentation Project is tasked with producing friendly, easy-to-read documentation for a worldwide audience. This means writing clean, clear documents with great attention to differences in cultures and languages. The Fedora Documentation Style Guide outlines specific rules and recommendations for documentation contributors. The style guidelines standardize documentation of both technical and non-technical information, to increase readability and comprehension.

The writers producing Fedora documentation come from a variety of backgrounds, each with different skill sets. Through use of the Fedora Documentation Style Guide, contributors produce and collaborate on documentation with consistent results. This style guide may vary from each contributor's familiar writing requirements. Practicing this guide will eventually become a comfortable standard with benefits outside of Fedora documentation. This style guide will demonstrate the rules and guidelines it sets forth.

The Fedora Documentation Style Guide borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. Any differences from those guides are intended to enhance the value of documents for international readers, and accommodate the technical nature of Fedora documentation. Particular care is made to adopt international standards for common notations to avoid confusion across cultural lines.

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

General Guidelines

The following sections provide guidelines for both sentence composition and syntax usage. Follow these guidelines to ensure your document's tone is consistent with that of other Fedora documentation.

Composition

Voice

Instructions and rules use an active voice, presenting confidence to the reader without sounding demanding. An active voice provides clear direction. It shows the reader what to do and gives expected results. Active voice leaves the reader with the impression an author stands behind the written work.

Avoid Passive Voice Unless Necessary
Passive voice is completely correct grammatically, but it is a barrier to reader comprehension. The passive voice flips conventional sentence structure around. It moves the verb and direct object forward to the first half of a sentence, and places the main subject in the second half of a sentence. Often a simple restructuring of the sentence makes it active. Long passive sentences frequently take multiple reads before a reader grasps the full meaning.

ACTIVE:  Select a strong password to improve personal security.
PASSIVE: Personal security improves by a strong password being selected.

Context

Avoid writing out of context. Adhere carefully to the subject matter of the document, chapter, section, and paragraph. Use references as appropriate, structuring documents so each new part builds upon the last. Avoid making the reader skip ahead to put current parts in context. Provide a link to related documentation if the reader may need it for clarification.

Emphasis

Emphasis is most effective when used sparingly. Use methods of emphasis such as boldface, underlining, or oblique text to draw attention to a new term. Use admonitions to set off notable material. Another acceptable way to emphasize a point is with varying sentence formation or word choice. The best documentation writers plan ahead for emphasis, applying it with careful consistency throughout the document.

Accuracy and Precision

Accuracy and precision make or break any document. This axiom applies equally to technical and literary accuracy. Choose words after considering as many usage cases as possible. For example, "go to" is not as precise as "click," yet "click" may not be accurate for all interface interactions. The term "select" is accurate in any usage case and sufficiently precise. Don't become too preoccupied in an attempt to cover all potential usage cases. Covering rare side cases elongates a document beyond reason, and the reader loses focus.

Tense

Tense is the time in which language takes place. There are three main tenses: past, present, and future. Select an appropriate tense for the document and adhere to it. For technical documentation, use the present tense whenever possible. Maintaining the same tense for each statement in a document is vital for clarity. Keep the same tense for all sequential tasks in a procedure.

Usage

Contractions

Avoid contractions, the combination of two words with an apostrophe replacing one or more letters. Contractions reduce the readability of documents and make translation more difficult. Other cultures and languages interpret contractions differently, and this confusion conflicts with the goals of the Fedora Documentation Project.

Pronouns

Pronouns are words language uses to replace specific noun phrases. Good writers must strike a balance between over-repeating a noun phrase, and using pronouns to stand in for nouns. A general rule to preserve clarity is to never repeat noun substitution with a pronoun in two consecutive sentences. Readers of technical documents need constant reminders on the exact subject the author is writing about. Prevalent use of pronouns cause readers to guess the subject a sentence is referencing. These assumptions reduce the effectiveness of documentation.

Avoid most personal pronouns in documentation, including the following:

• Subjective personal pronouns ("I," "he," "she," "it," "we,")
• Objective personal pronouns ("me," "her," "him," "us")
• Possessive personal pronouns ("my," "her," "his," "our")

Also avoid:

• Reflexive pronouns, such as "yourself" or "himself"
• Intensive pronouns, such as "he himself" or "(you) do it yourself"
• Resist overuse of "you", "your", and "one/one's"

Occasionally situations require the second personal pronoun "you," and its attendant forms for clarity. Maintaining an active voice is paramount over avoiding the second personal pronouns. "You" and "your" are appropriate words to indicate action or possession on the part of the reader.

Indefinite pronouns such as "this" or "that" without an antecedent make it tough for a reader to follow an author's meaning. Favor writing an exact noun phrase whenever possible over the vague words "this," "these," "those," and "that."

INCORRECT:  Edit your yum configuration files to use geographically close mirrors.  This allows you to
update your system faster.

CORRECT:  Edit the yum configuration files to use geographically close mirrors for faster system updates.

When eliminating indefinite pronouns, a cumbersome long sentence may result from joining too many clauses. Use indefinite pronouns to break long sentences up to improve clarity, but always provide a proper antecedent.

INCORRECT: Stay current with recommended updates to your operating system in order to improve functionality of 
applications, remove security risks, and automatically resolve performance issues solved from bug reports.

CORRECT: Stay current with recommended updates to your operating system. These updates improve functionality of 
applications, remove security risks, and automatically resolve performance issues solved from bug reports.

Sentence Formation

Keep sentences as short as possible. Cutting unnecessary words is vital to strengthen meaning. There are a number of common traps technical writers fall into resulting in lengthy sentences.

Indirect Discourse

Indirect discourse refers to the use of "that" to attribute a statement, fact, or feeling in a sentence without the use of quotation marks. In regular writing, it weakens statements of fact. Documentation writers can improve the impact of sentences by removing "that" and "which."

INCORRECT: Fedora is an open source operating system that is upstream for many other open source projects.

CORRECT: Fedora is an upstream open source operating system for many other open source projects.

Other Unnecessary Word Combinations

Avoid using the unnecessary word "then" following an "if" statement. When a sentence begins with an "if" statement, follow it with a comma and complete the sentence with a full statement.

INCORRECT: If an email client will not send or receive messages, then check under the File Menu and 
verify "Work Offline" mode is unselected.

CORRECT: If an email client will not send or receive messages, check under the File Menu and 
verify "Work Offline" mode is unselected.

Many words we use in everyday conversation reduce impact in printed materials because they "leave a way out." These are words preceding verbs and nouns to minimize the sentence's influence. This is not an exhaustive list, but mindful documentation writers will reduce using these words and those of a similar nature.

Avoid Reducing Impact With Unnecessary Words
The following words minimize the impact of the verb or noun clause within a sentence. Other words also fit into this category, but this short list is aimed at helping documentation writers identify words of this nature and eliminate them from their writing: should, could, may, might, perhaps, some, many, most, numerous, few, somewhat, whatever, possibly, can, occasionally, and frequently.

Sentence Variation

For the strongest impact, keep the first and last sentences of a paragraph as short as possible. Varying sentence length within a paragraph and through the entire document keeps a reader's attention. A short and simple fact is easy to grasp and use to analyze the next sentence's topic. There is nothing wrong with using longer sentences to explain complex ideas and concepts. Try to use a simple synopsis sentence at the end of each paragraph to give readers a reprieve and recap of any important information. A short final sentence stays with the reader to the next section.

Capitalization

In sentences, capitalize the first word. Do not start sentences with a command, package, or option name.

INCORRECT: <code>smolt</code> provides hardware profiling.
CORRECT: The <code>smolt</code> package provides hardware profiling.

In headings, always capitalize the first word regardless of the type of speech. All subsequent words are also capitalized other than articles ("a," "an," or "the"), short prepositions ("in," "of," "for," "with," "at," "on"), or conjunctions ("and," "but," "or").

Examples:

• Avoid Using Contractions in Technical Writing
• Try to Do the Right Thing
• Find the Right Way to Say What You Mean
• The Grass is Always Greener on the Other Side of the Fence

Punctuation

Punctuation is a crucial component of understanding prose. A misplaced comma, period, or an improper punctuation mark changes a sentence's meaning entirely. Punctuation marks are the fasteners in a writer's toolbox. Readers are accustomed to the regular nails and screws, like commas and periods. Start throwing in lots of flashy hinges or braces like semicolons or ellipsis, and the unfamiliar notations easily distract readers. Complex punctuation marks are not universal, hindering translation efforts of Fedora Documentation.

Minimize the following punctuation marks in documentation:

• Parentheses or "em dashes." To compensate, rearrange the sentence, or break it into two complete thoughts.

• Semicolons Good to use only if two thoughts are related, must be joined for clarity, and removes the need for a conjunction.

• Colon If there are more than three items, use a bulleted list for easy comprehension.

• Ellipsis Do not use for stylistic emphasis... only to denote an indefinite continuation of content in an example.

• Exclamation points In technical writing this is accepted for use only as a most dire "warning" admonition, not for emphasis.

• Ampersands The word "and" is to be written out, and this mark only reserved if it is part of a computer command.

• Slashes Do not use slashes for a short hand version of "he or she" by using he/she, instead use the words "and," "or," or "either." Slashes are commonly used in file paths and using them otherwise will create confusion.

Other Writing Questions

Every writer hits writing obstacles. It becomes difficult to adequately phrase something, or the words just do not "sound right." This is why the Fedora Documentation Project is a team effort. Call on fellow documentation writers in the mailing list or chat room for help with wording and formatting issues. Another trick professional writers use everyday is time away from the project. Take a break away from the document. Returning to a troublesome spot with fresh eyes is often all that is needed to overcome the writing hindrance.

The overall goal of the Fedora Documentation Project is to provide assistance to Fedora users in easy-to-understand language. You do not have to write to impress an English professor, or show off your expertise in a subject matter. Short sentences, frequent definitions of new and unfamiliar terms, and reference links are all aids our audience appreciates most. Write with your target audience in mind, and it will be your documentation contributions with the highest visits of users in need of answers.

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Content and Rendering

Writing documentation for display on assorted media through various technologies presents unique requirements. In general, keep the written content and rendering information separate. Rendering information is the formatting markup language to distinguish types of information, such as bold text to add emphasis. Modern technologies empower writers to use specialized markup language to enhance communication. It is imperative writers participating in collaborative projects like the Fedora Documentation Project adhere to standards and prescribed templates.

Benefits of Content and Markup Language Separation
Keeping content material and markup language separate from each other within documentation adds an additional benefit. As new media formats develop, project coordinators easily remove markup language and re-format the original content for the new communication outlet. Therefore, separating markup language from subject matter content encourages use of the original content for future projects with little additional effort.

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Dates and Times

The styles used for dates and times vary widely around the world, and this creates a lot of confusion. While there is consensus on one calendar for most business purposes, the dates on this calendar can be represented in many different ways. The varying uses of daylight saving time and assorted ways of representing time can make even simple communications more difficult. International standards have been developed to effectively communicate dates and times, and these standards should be used for publications that may reach a global audience.

Absolute Dates and Times

Absolute dates and times specify specific points in time and may include points in the past, present, or future.

The ISO 8601 standard provides a simple way to represent dates and times that is easily recognized around the world and is equally easy to use. Under this standard, all values are ordered from most to least significant. Write all absolute dates and times in accordance with the ISO 8601 standard.

Absolute Dates

Absolute dates are written with the four-digit year first, the two-digit month second, and the two-digit day last. Each value is separated with a hyphen. This format is written as "YYYY-MM-DD".

Absolute Times

Absolute times are written with the two-digit hour first and the two-digit minute second. Each value is separated by a colon. This format is written as "HH:MM".

Additional precision is provided using seconds. Seconds are written as two-digit integers. Minutes and seconds are separated by a colon. This format is written as "HH:MM:SS".

Any fraction of a second is written as a decimal number. No limit is placed on the precision used. For example, to use precision of 1/100th of one second, this format is written as "HH:MM:SS.NN".

Absolute times are followed by a timezone specification. The Coordinated Universal Time (UTC) is a universally recognized time standard and is preferred for absolute time specifications. This is sometimes referred to as Greenwich Mean Time (GMT) or Zulu Time (Z). The preferred way to specify a time in UTC is to follow the time with a space and "UTC". This format is written as "HH:MM UTC".

Time Intervals

Empty

Recurring Events

Empty

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Fedora-Specific Conventions

The Fedora Project uses specific conventions that extend beyond the general style rules and guidelines. These conventions exist to produce specific results from the toolchains or to better address the specific requirements of the Fedora Project.

Screenshots and Images

Images and especially screenshots are hard to maintain, hard to translate, and have to be changed constantly with every test.

Screenshots do not give any more information than is already given with the text. The user is most often following along with the instructions, so the screen is up in front of them already.

Many people perceive that screenshots are necessary in help documents, often because they've seen other documents use screenshots. Avoid this trap. Screenshots lower the quality of the document by taking up valuable space with repetitive imagery and distracting authors from maintaining the far more valuable content.

Diagrams are different from screenshots. A diagram is a graphic that is self-descriptive and in many cases can be very useful or show things that cannot be described as well with words. In such cases it is worth the extra effort to maintain the graphic, including dealing with localization. Fortunately, most documents do not need more than one or two diagrams.

General Conventions

Software Management

Software that appears in any official Fedora documentation must adhere to these guidelines:

• Software must be available in the official Fedora software repositories for the release of Fedora to which the documentation applies.
• Software installation must be done via Fedora software management tools, preferably yum. If you document using GUI tools for package installation and management, cover the default application (pirut) before others, and cover it consistently.
• Software must not require user compilation from source, or rebuilding from source RPMs.
• Guides must not encourage reconfiguration of file system resources, security contexts, or any other resources from a software package that conflict with the intention of the maintainer for that software package.

Administration Tools

Guides must use the following conventions for system administration:

• Neither assume, nor configure, sudo rights. Use the following command instead:

su -c "<COMMAND>"

• To configure the current or persistent activation of services through initscripts, use the /sbin/chkconfig and /sbin/service binaries.

DocBook XML

The preferred format for long-term maintenance of documents is DocBook XML. This format stores contextual style information without concern for document rendering and avoids common limitations of other document storage formats.

Wiki

Wiki markup is a structured form of plain text that is not as complex as DocBook XML and has become a popular format for new writing. The wiki format and the limited available markup are simple. Wiki is easy to read and edit in normal plain text editors. Unfortunately, it lacks the contextual markup that DocBook XML provides. The Fedora Project has adopted specific conventions to provide basic contextual support in the wiki format.

ReST

ReST is a lightweight structure form of plain text that can be used to produce meaningful XML output.

Plain Text

Plain text documents contain no markup for style or context. They also lack any inherent structure. Original writing in plain text generally requires revision, including the addition of markup, before publication. A plain text document that uses wiki conventions and markup is easier to translate into wiki format, and using those conventions can improve the readability and structure of the document.

Other Formats

There are many other formats for text storage. Each may provide different features and drawbacks. If a specific structure is adhered to, the amount of effort required to convert documents between different formats can be minimized.

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Common Mistakes

Writers, even experienced ones, frequently make some simple mistakes. Once writers develop correct usage into habits, they can avoid these mistakes.

Spelling

The following words appear in texts frequently and are often spelled incorrectly. This list does not include locale-specific differences in spelling.

INCORRECT:  dependant, dependancies
CORRECT:    dependent, dependencies

INCORRECT:  kernal
CORRECT:    kernel

INCORRECT:  seperate
CORRECT:    separate

Grammar

A v. an -- The choice of which article to use, 'a' or 'an', is made by the sound of the first letter of the word following the article. The 'a' is used when the initial sound is a consonant, the 'an' is used when the initial sound is a vowel. The word 'SSH' starts with the "ess" sound, so the 'an' is used.

One common confusion is with acronyms and abbreviations, because that can change how you pronounce something. For example, if 'URL' is pronounced "You arr ell," it is "a URL". If 'URL' is pronounced "Earl" ("Urrl"), it is "an URL."

References: http://www.drgrammar.org/faqs/#36 and http://grammar.ccc.commnet.edu/GRAMMAR/abbreviations.htm

Punctuation

Sentences using "which" or "that" to separate statements frequently contain mistakes in the usage of commas. An instance of "which" is preceded by a comma, which is often forgotten. Instances of "that" are often incorrectly preceded by a comma that should not be present. When in doubt, trust your ear. "Which" wants a pause before it and "that" does not.

Use a comma for serial lists before the last item, that is:

"Foo, bar, and baz."

... not ...

"Foo, bar and baz."

Without the final comma, it is hard to tell if the final item is a "bar" or a "bar and baz". (Writers and editors sometimes refer to this punctuation as a "Harvard comma" or "serial comma.")

Contractions

Avoid contractions in professional writing. They are rarely needed or desired, and they are a common source of errors. When using them, writers often make errors that include spelling, placement of apostrophes, and improper usage within a sentence. The first rule to remember about contractions is that the apostrophe should be placed where the last omission of letters occurs.

Other Mistakes

Empty

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Quick Reference

Numbers

When to Spell Out a Number

Rules for using Arabic numerals or spelling out numbers are as follows and are listed from highest priority to lowest.

• If the number is part of a casual expression, spell it out.
• If the number is a calendar year, do not spell it out.
• If the number is an age or percentage, do not spell it out.
• If the number begins a sentence, spell it out. Awkward sentences should be reformed.
• If the number is greater than 10, do not spell it out.
• If the number is one through nine, spell it out.

When to Use Roman Numerals

• Use Roman numerals for wars and honorific suffixes.

World War II
John Doe III

Cardinal Numbers and Ordinal Numbers

• Cardinal numbers include figures 1, 2, 10, 101, and so on, and the corresponding words.
• Ordinal numbers include the terms 1st, 2nd, 10th, 101st, and so on, and the corresponding words.

Large Numbers

• When spelling out large numbers, connect words ending in 'y' to subsequent words within the same number with a hyphen.
• Avoid commas between words that are part of one number.

twenty-one
one hundred thirty-one
twenty-five thousand one hundred thirty-one
ninety bottles

Proper Names

• Write proper names according to the owner's practice.

Abbreviations

The United States

• As a noun appearing alone, use "United States."

...the government of the United States...

• As a noun appearing as part of a locality, use "US" with no periods and no spaces.

Raleigh, NC, US
US, Earth

• As an adjective, use "U.S." with no spaces.

...the U.S. government...

States

• Spell out state names when they appear alone.

...the government of North Carolina...

• When abbreviating state names, use their two-letter ZIP standard abbreviations.
• Abbreviate state names when they appear as part of a locality.

Raleigh, NC

• Place one comma between the city and state name and another after the state name, unless it ends the sentence or is part of a dateline.

...founded in Raleigh, NC, by Red Hat...
...managed from Raleigh, NC.

Academic Degrees

• Avoid abbreviating degrees.
• Use an apostrophe in bachelor's degree, master's, etc.
• Do not use an apostrophe in Bachelor of Arts, Master of Science, etc.
• Use abbreviations only when the preferred method would be cumbersome.
• Use abbreviations only after a full name.
• Set abbreviations apart with commas.

Dates

• Spell out days of the week and separate them from dates using a comma.
• When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD). Read more about dates and times on the DatesAndTimes page.
• When listing a day and month:
• List the day first.
• Spell out the day.
• Set the day and month apart with "of."
• Spell out the month.
• When listing a month and year:
• List the month first.
• Spell out the month.
• Set the month and year apart with "of."
• Use Arabic numerals for the year.

Sunday, 2000-01-01
2000-01-01
The first of January
January of 2000

Times

• Use 24-hour time formats.
• Always use figures.
• Follow absolute times with a timezone specification.
• Separate days, hours, minutes and seconds with a colon and no spaces.
• Separate seconds and fractions thereof with periods.
• If the scope of a specification is unclear, increase the precision or specify the scope of the lowest precision.
• Use Coordinated Universal Time (UTC) for all worldwide events. Refer to the DatesAndTimes page for more information about UTC.
• Localized events may be specified using UTC or the local time, but always specify a timezone or offset.

15:00 UTC
1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second)
15:00 minutes (15 minutes)
15:30 hours (15 hours and 30 minutes)
The global conference will take place at 15:00 UTC.
The event will be in Raleigh, NC, and will take place at 11:00 UTC-4.

Punctuation

Commas

For consistency and to avoid ambiguity, use a serial comma after every item in a list save the last. This usage is sometimes called the "Harvard comma" or the "Oxford comma."

spam, spam, spam, and eggs

Do not use a serial comma in the name of companies such as law firms.

Dewey, Cheatam & Howe

Lists

• Capitalize and use periods when the list items are complete sentences.
• Make them agree so that there aren't a mixture of sentences and fragments.

You could also have a list with a colon:

• that was lowercase and not punctuated
• that again doesn't mix forms
• that is likely very short

Titles

• Avoid punctuation in titles, with the exception of hyphens.
• Avoid abbreviations in titles. Spell words out and introduce abbreviations in the body text.

Units of Measure

• Metric units are preferred.
• Use the prefixes published by the International Electrotechnical Commission (IEC) as part of IEC 60027-2 A.2 to express quantities of binary data.

Common Technology Terms

• cyberspace
• database
• dot-com
• DSL
• email
• FLOSS (free/libre open source software)
• home page
• hyperlink
• hypertext
• Internet
• intranet
• log in (intransitive verb)
• log into
• login (noun)
• online
• shareware
• Web (proper noun)
• webcast
• webmaster
• website
• World Wide Web

Denoting trademarks

Never use the trademark symbol (™) or the registration mark (®). If for any reason the Fedora Project is obliged by contract to mention other trademarks in a legend, add the legend as required by the contract.

In addition, all documentation should contain the disclaimer: "All other trademarks are the property of their respective owners." This marking is standard in all Fedora Documentation toolchains at the time of this writing.

Old page
The data in this page has been incorporated into a formal guide and is no longer being maintained.

Resources

Useful FLOSS Project Guides

• http://library.gnome.org/devel/gdp-style-guide/stable/ - GNOME Documentation Style Guide

Other Style Guides

• http://www.ap.org/ - The Associated Press
• http://www.chicagomanualofstyle.org/ - The Chicago Manual of Style
• http://en.wikipedia.org/wiki/Style_guide - Wikipedia article on style guides

US-English Grammar

• http://www.grammarbook.com/grammar/subjectVerb.asp - The Blue Book of Grammar and Punctuation provides examples of common difficulties encountered when writing in English. The Table of Contents covers "Who and Whom", "Who vs. Which vs. That" to "Effective Writing". Provides useful and clear examples with memorable tools.

Standards

• http://en.wikipedia.org/wiki/ISO_8601 - Wikipedia article on ISO-8601, "Data elements and interchange formats -- Information interchange -- Representation of dates and times"
• http://en.wikipedia.org/wiki/UTC - Wikipedia article on Coordinated Universal Time
• http://en.wikipedia.org/wiki/Binary_prefix - Wikipedia article on binary prefixes

DocBook

• http://www.docbook.org/ - Documentation for DocBook

Other Resources

• http://www.m-w.com/ - Merriam-Webster Online