[Patternfly] Terminology and Wording Review Request
Leslie Hinson
lhinson at redhat.com
Fri Jan 23 21:12:54 UTC 2015
Thanks Ju. I’ve also added this to the queue. As a reminder to everyone, we do have an etherpad where you can add any requests. See: http://etherpad.corp.redhat.com/terminologyandwording <http://etherpad.corp.redhat.com/terminologyandwording>
Regards
Leslie
> On Jan 23, 2015, at 4:06 PM, Ju Lim <julim at redhat.com> wrote:
>
> Another abbreviation that would be appreciated would be for Queue Length/Depth. This is often on anything to do with performance.
>
> Is it qlen or qdepth?
>
> In days of yonder past (Unix and early Linux), queue length (qlen) was more common. Queue depth seems to be more common these days. Used in CFME and it gets mentioned in pretty much any performance context where queueing occurs. I'd lean to qdepth but would be nice if its specified.
>
> Thanks,
> Ju
>
> On Jan 23, 2015, at 10:00 AM, Ju Lim <julim at redhat.com <mailto:julim at redhat.com>> wrote:
>
>> Yes IO == I/O == Input / Output
>>
>> Cheers,
>> Ju
>>
>> On Jan 23, 2015, at 9:23 AM, Leslie Hinson <lhinson at redhat.com <mailto:lhinson at redhat.com>> wrote:
>>
>>> Hey Ju,
>>>
>>> Thanks so much for reviewing this. Your technical input is valuable. See inline comments below.
>>>
>>>> On Jan 22, 2015, at 1:17 PM, Ju Lim <julim at redhat.com <mailto:julim at redhat.com>> wrote:
>>>>
>>>> Hi Leslie:
>>>>
>>>> I've some concerns that the abbreviation list is showing some inconsistencies. Specifically, I think
>>>> b/s should be bps
>>>> B/s should be Bps
>>>>
>>>> Otherwise, you need to change IOps to IO/s, KBps to KB/s, MBps to MB/s, TBps to TB/s, etc.
>>>
>>>> For IOps, IMHO, I think it should be IOPS (which standards for I/Os per second -- I/Os is plural). That's the industry-standard way it's written (though admittedly, it could be confused with Internet Official Protocol Standards… a standard in the IETF world). In the storage and networking industry, that's the standard way it's written plus it's also written that way in several dictionaries online, SNIA (one of the storage authorities), etc.
>>>
>>> I agree this needs to be consistent. We will definitely take a look at this again.
>>>
>>>>
>>>> Note: the abbreviation list (MBps, Mbps, etc.) currently also conflicts with the statement above the abbreviation list table:
>>>> * Use the slash (/) with measurements to indicate the word per. For example: 100 MB/s (100 megabytes per second)
>>>
>>>>
>>>> The non-abbreviation for nanosecond (has no space) -- feel free to verify with the various dictionaries online. Just like millisecond is 1 word and not milli second.
>>>
>>> Got it.
>>>>
>>>> Do we have any abbreviations to recommend for the following, e.g.
>>>>
>>>> I/O or IO == I/O
>>>
>>> Shouldn’t this be “IO == Input/Output”?
>>>
>>>> yr == year
>>>> mth == month
>>>> qtr == quarter
>>>>
>>> We can add these. Allie is working on a design effort for Portal Scorecard that might benefit from these particular abbreviations. That said, we will need to investigate a little more to ensure we are using the appropriate abbreviations for these. For example, “mo” is an another abbreviation for month. As an extension to this, I think we could also add the appropriate abbreviations for months (e.g. Feb) and days (e.g. Wed). Anyway, I’ll add this to our queue.
>>>
>>> We’ll send an update when we have one.
>>>
>>> Thanks again, Leslie
>>>
>>>> Thanks,
>>>> Ju
>>>>
>>>> On Jan 21, 2015, at 5:37 PM, Andres Galante <agalante at redhat.com <mailto:agalante at redhat.com>> wrote:
>>>>
>>>>> 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 <http://developer.android.com/design/style/writing.html>
>>>>>
>>>>>
>>>>>
>>>>> ----- Original Message -----
>>>>> From: "Leslie Hinson" <lhinson at redhat.com <mailto:lhinson at redhat.com>>
>>>>> To: patternfly at redhat.com <mailto: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 <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>
>>>>>
>>>>>
>>>>>
>>>>> 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 <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#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 <http://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.
>>>>>
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Patternfly mailing list
>>>>> Patternfly at redhat.com <mailto:Patternfly at redhat.com>
>>>>> https://www.redhat.com/mailman/listinfo/patternfly <https://www.redhat.com/mailman/listinfo/patternfly>
>>>>>
>>>>> _______________________________________________
>>>>> Patternfly mailing list
>>>>> Patternfly at redhat.com <mailto:Patternfly at redhat.com>
>>>>> https://www.redhat.com/mailman/listinfo/patternfly
>>>>
>>>
>>
>> _______________________________________________
>> Patternfly mailing list
>> Patternfly at redhat.com <mailto:Patternfly at redhat.com>
>> https://www.redhat.com/mailman/listinfo/patternfly
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/patternfly/attachments/20150123/2d5bed2f/attachment.htm>
More information about the PatternFly
mailing list