Archive:Docs Project Style Guide - Quick Reference

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Imported from MoinMoin)
 
(4 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{header|docs}}
 +
 
== Quick Reference ==
 
== Quick Reference ==
  
Line 209: Line 211:
 
* World Wide Web
 
* 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.
  
 
<!--TODO: The Quick Reference should summarize all of the rules and guidelines.
 
<!--TODO: The Quick Reference should summarize all of the rules and guidelines.
 
-->
 
-->
 +
[[Category:Docs Project process]][[Category:Documentation]]

Revision as of 02:54, 26 February 2009

DocsProject Header docTeam1.png


Contents

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

Periods

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

Colons

Other Punctuation

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.

Markup

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.