[Patternfly] Terminology and Wording Review Request

Wed Jan 21 22:37:36 UTC 2015

Hi Leslie,

I think this is fantastic, I find the Capitalization very helpful plus those rules can be applied to any language. 

On Android design guidelines, there is a section about writing. It has a nice "Dos and Donts" table:
http://developer.android.com/design/style/writing.html

----- Original Message -----
From: "Leslie Hinson" <lhinson at redhat.com>
To: patternfly at redhat.com
Sent: Tuesday, January 20, 2015 11:05:30 AM
Subject: [Patternfly] Terminology and Wording Review Request

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 

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 and 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 

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 

    1. 
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 

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 

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 . 

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/ 

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 

    * 

Use acronyms consistently. 

_______________________________________________
Patternfly mailing list
Patternfly at redhat.com
https://www.redhat.com/mailman/listinfo/patternfly