From 3817383e8818d9cef831dcda2f3822f7cfe2ea8b Mon Sep 17 00:00:00 2001 From: Jared Smith Date: Mar 02 2018 09:28:24 +0000 Subject: Add sections on numbers and abbreviations --- diff --git a/_topic_map.yml b/_topic_map.yml index 887f269..25613d8 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -49,3 +49,7 @@ Topics: File: syntax-usage - Name: Dates and Times File: dates-times + - Name: Numbers + File: numbers + - Name: Abbreviations + File: abbreviations diff --git a/en-US/style-guide/abbreviations.adoc b/en-US/style-guide/abbreviations.adoc new file mode 100644 index 0000000..5c7cec2 --- /dev/null +++ b/en-US/style-guide/abbreviations.adoc @@ -0,0 +1,54 @@ +== 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. diff --git a/en-US/style-guide/dates-times.adoc b/en-US/style-guide/dates-times.adoc index d2c83d4..af9409c 100644 --- a/en-US/style-guide/dates-times.adoc +++ b/en-US/style-guide/dates-times.adoc @@ -1,21 +1,63 @@ == 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. +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 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`. +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. + +=== Dates + +Use the following guidelines when writing general 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) to avoid confusion. +* 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. + +.Examples +---- +Sunday, 2000-01-01 +2000-01-01 +The first of January +January of 2000 +---- + +=== Times + +Use the following guidelines when writing general times: + +* Use 24-hour time formats. +* Always use units. +* 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. +The Coordinated Universal Time (UTC) is a universally recognized time standard and is preferred for 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`. +* Localized events may be specified using UTC or the local time, but always specify a timezone or offset. + +.Examples +---- +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. +---- diff --git a/en-US/style-guide/numbers.adoc b/en-US/style-guide/numbers.adoc new file mode 100644 index 0000000..5c7d876 --- /dev/null +++ b/en-US/style-guide/numbers.adoc @@ -0,0 +1,50 @@ +== 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. + +.Examples +---- +Five horses ran in the field. +Fedora 27 was released in 2017. +I cannot eat 27 slices of pizza. +I built eight packages for Fedora. +---- + +=== When to Use Roman Numerals + +Use Roman numerals for wars and honorific suffixes. + +.Examples +---- +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. + +.Examples +---- +twenty-one +one hundred thirty-one +twenty-five thousand one hundred thirty-one +ninety bottles +---- diff --git a/en-US/style-guide/writing-guidelines.adoc b/en-US/style-guide/writing-guidelines.adoc index 9c1bfb2..f35052c 100644 --- a/en-US/style-guide/writing-guidelines.adoc +++ b/en-US/style-guide/writing-guidelines.adoc @@ -23,8 +23,8 @@ Review your writing for spelling mistakes and grammar abuse. === Use Active Voice -Instructions and rules use an _active voice_, presenting confidence to the reader without sounding demanding. -An active voice provides clear direction. +Write instructions and rules using an _active voice_, presenting confidence to the reader without sounding demanding. +An active voice provides clear directions. It shows the reader what to do and demonstrates expected results. Active voice leaves the reader with the impression an author stands behind the written work.