Docs Project Style Guide - Quick Reference
From FedoraProject
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
- 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.
