[Patternfly] Terminology and Wording Review Request

Tue Jan 20 14:05:30 UTC 2015

Hey everyone, 

Recently we kicked off an effort to define and establish some best practices for terminology and wording as a tool to promote consistency. The goal is to publish these guidelines to PatternFly so that it is readily available for designers, developers and others to use as needed. 

Below you will find standards that we have established for terminology and wording as well as general rules regarding capitalization, punctuation, abbreviations and acronyms. As part of our review process, we would like to gather feedback from you to ensure there are no major issues or concerns with the definitions below. Please provide your input by end of day on Tuesday, Jan 27. 

Look forward to hearing from you, 
Leslie

Terminology and Wording 
Login (n): Please note that Portal does use Login (i.e. username or user ID) and will continue to do so 
Log In (v): Log In should be used on the button for the Login page. 
Username (n): Usually a unique ID you type in with your password (e.g. ssmith123). Should be used on the product login screens. 

Capitalization 
Headline style
For headline style, capitalize the first letter of every word except for articles (a, an, the), coordinating conjunctions (and, but, or), and prepositions of three letters or fewer (of, on, by, in). There’s one exception: Any word that is the first word in the headline or the last word should be capitalized, regardless of its part of speech.  

For example, “Where to Install”
Sentence style
For sentence style, capitalize the first letter of the first word and any proper nouns.  Use sentence style for blocks of text and as described in “Capitalization for Common Components.”

For example, “Only show subscriptions that match this Subscription Asset Manager Organization.”  

Capitalization for Common Components 

Button labels
Headline
Checkbox labels
Sentence
Column heading labels
Headline
Error messages
Sentence
Group headings, group boxes
Headline
List boxes
Sentence for introductory text
Headline for list box labels 
Prompts
Sentence
Radio buttons labels
Sentence
States (as shown in tables, filters, e. g. Up and Running)
Headline
Status messages
Sentence
Tab labels
Headline
Text box labels
Headline
Tool tips
Sentence
Window titles (browsers, dialog boxes, steps in a wizard)
Headline

Punctuation for RCUE

Ampersands
Avoid using ampersands.  Use “and” instead.
Colon
Use sentence style capitalization for introductory text that appears above a control. A colon follows the introductory text. 
Comma
Use serial commas. A serial comma is the comma before the “and” in a series of three or more items: “Item 1, item 2, and item 3.”
Taken from https://mojo.redhat.com/docs/DOC-28115#commas
Currency
For currencies that use the symbol $ alone, modify with the first two letters of the ISO code. Eg: US$1,500 (United States), AU$1,500 (Australia), HK$1,500 (Hong Kong), CA$1,500 (Canada). For other currencies, use the national currency symbol whenever possible (£1,500 = British pound; €1,500 = Euro, ¥1,500 = Japanese Yen, etc.). Generally, we do not provide currency conversions.
Taken from https://mojo.redhat.com/docs/DOC-28115#currency <https://mojo.redhat.com/docs/DOC-28115#currency>
Ellipses
Use an ellipsis (...) to indicate that text is truncated. 
Exclamation point
Avoid using exclamation points, except when referring to a command, such as the bang ( ! ) command.
Hyphenation
Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated.  Prefixes can include "multi," "non," "sub," "co," "semi," "pre," "re," etc.

Exceptions: When not hyphenating makes it unclear. For example: He recovered his health. He re-covered the leaky roof. (AP)

You will usually hyphenate:
Complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. Examples: cloud-based solutions, right-side paralysis, system-wide menu.  Exception: We never hyphenate "open source," even when used as a complex adjective.
When the prefix ends in a vowel and the word that follows begins with the same vowel. Examples: semi-independent, pre-emptive. Exceptions: cooperate, coordinate
Capitalized words with a prefix.  Examples:  un-American, non-British
Double prefixes. Examples: sub-subparagraph, re-sublet
Do not hyphenate words with the prefix “non” unless the dictionary says otherwise: nonaddictive, nonabrasive, nonalcoholic.  
Taken from https://mojo.redhat.com/docs/DOC-28115#hyphenation <https://mojo.redhat.com/docs/DOC-28115#hyphenation> and https://mojo.redhat.com/docs/DOC-28115#non <https://mojo.redhat.com/docs/DOC-28115#non>
Percent 
In text, use the word percent. For example: 10 percent to 20 percent
In tables, use the percent symbol. For example: 10% to 20% 
Question mark
Place a question mark at the end of a question. For example:
Are you sure you want to delete this file?

General Rules about Abbreviations
Use abbreviations that users are familiar with and write out uncommon abbreviations. 
Do not write out units of measure. [See "Abbreviations for Units of Measurement"]
Use abbreviations consistently.

Common Abbreviations for RCUE
General Abbreviations

e.g. and i.e.
Use sparingly. e.g. means “for example.” i.e. means “in other words.” Add commas after each (e.g.,). 
Adapted from https://mojo.redhat.com/docs/DOC-28115#e <https://mojo.redhat.com/docs/DOC-28115#e>
KVM
kernel-based virtual machine
sysadmin
Avoid using abbreviations like "sysadmin" and "SysAdmin;" these are too informal. "System" should be singular (i.e., not "systems administrator"), because it can include both a single system and multiple systems, similar to "database administrator" or "brain surgeon," who work on more than one database and brain, respectively.
Taken from https://mojo.redhat.com/docs/DOC-28115#systemadministrator <https://mojo.redhat.com/docs/DOC-28115#systemadministrator>
S.
As a noun, use "United States" unless there are space constraints. As an adjective use "U.S." (e.g., U.S. soldier). As part of an organization, use "U.S."
Taken from https://mojo.redhat.com/docs/DOC-28115#us <https://mojo.redhat.com/docs/DOC-28115#us>
VM
virtual machine.  OK to abbreviate as long as you've spelled it out once in first occurrence and as long as "VM" won't be confused with other terms that share that acronym.
Adapted from https://mojo.redhat.com/docs/DOC-28115#vm <https://mojo.redhat.com/docs/DOC-28115#e>
Units of Measure Abbreviations
General Guidelines		
Use the following guidelines for abbreviations of measure:

Include a space between a number and a unit of measure. For example: 55 MB
Use the numeral, not the word, with abbreviations of units of measurement. For example: 5 ft, not five ft
Use only the singular for the abbreviation. For example: 5 lb, not 5 lbs
Use the slash (/) with measurements to indicate the word per. For example: 100 MB/s (100 megabytes per second)
Use a hyphen with a numeral and a spelled-out unit of measurement when used as a compound modifier. Do not hyphenate number and unit of measurement compound modifiers when the measurement unit is abbreviated. For example: 1-foot clearance; 1 ft clearance
In specifications that include both U.S. and metric values, show the U.S. value first (followed by the metric value in parentheses). For example: Rackmount depth: 29 in. (73.7 cm)
For temperature, include the degree symbol with each number. For example: 10° C to 25° C
Abbreviation List

b
bit
b/s
bits per second
B
byte
B/s
bytes per second
C
celsius
F
fahrenheit
Gb
gigabit
GbE
gigabit Ethernet
GB
gigabyte
hr
hour
IOps 
I/O per second
KB
kilobytes
KBps
kilobytes per second
Mb
megabit
Mbps
megabits per second
MB
megabytes
MBps
megabytes per second
ms
millisecond
ns
nano second
PB
petabyte
P/N
part number
% 
percent
s
second
states
Use the two-letter postal abbreviations. Refer to stateabbreviations.us <https://mojo.redhat.com/document/stateabbreviations.us>.
TB
terabyte
TBps
terabytes per second

Abbreviations for Time and Time Zones
When referring to time zones, use this chart: http://www.timeanddate.com/time/zones/ <http://www.timeanddate.com/time/zones/>
AM
ante meridiem (before noon)
PM
post meridiem (after noon)

General Rules about Acronyms 
Use acronyms that users are familiar with and write out uncommon acronyms 
Write out all Red Hat product names when possible. If not, refer to the shortened product title names. Official product name list: https://mojo.redhat.com/docs/DOC-938543 <https://mojo.redhat.com/docs/DOC-938543>
Use acronyms consistently.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/patternfly/attachments/20150120/6435f56d/attachment.htm>