Writing Standards - cdig/docs GitHub Wiki

These guidelines apply to all public-facing writing, company-wide.

We write in plain English. We generally follow Associated Press (AP) style rules because they're simple and easy to remember.

If you're having trouble solving a particular writing challenge, here are some tips.

• Check these guides first. They're the most up-to-date resource.
• Look for similar examples from our existing writing, and be consistent.
• Ask others on the team whether they have a sense of how to solve it.
• Look for examples in industry publications.
• See whether it's covered in Grammar Girl, the English Stack Exchange, or Wikipedia.
• Search the web for a consensus among good writers.

If you solve a writing problem not covered here, add it to this page to help the rest of us follow your lead.

• Content-Specific Tips
  • Lesson Objectives
  • True or False Questions
  • Multiple-Choice Questions
• Titles
• Commas
• Em Dashes
• Bulleted Lists
• Abbreviations
• Adjectives
• Hyphenation
• Spellings & Word Choice
• One Word or Two?
• Numbers
• Mathematical & Special Symbols
• Units of Measurement

Objectives need to be written as measurable goals. To do this, use action verbs to begin each objective.

Write objectives so that they could follow the unspoken phrase, "After completing this lesson, you should be able to..."

Here's a handy list of action verbs. This is not a CDIG list, and there are a few words, like "discuss", that are less measurable than we'd ideally like.

• Capitalize "True" and "False". No terminal punctuation needed.
• Most true or false "questions" are actually statements. Don't give them a question mark unless you have actually phrased them as a question!

See Bulleted Lists.

If you want a quick fix, here's a tool you can use to capitalize titles for you: http://titlecase.com (Use AP Style Title Case)

Capitalize all words except for: a, an, and, at, but, by, for, in, nor, of, on, or, so, the, to, up, yet.

Here's a good reference on the title capitalization rules we adhere to: http://www.quickanddirtytips.com/education/grammar/capitalizing-titles

When the title includes a number, it's preferable to spell it out — "Part One" rather than "Part 1".

When the title includes an "and", it's preferable to use an "&". An exception would be when the "and" is at the end of a list — prefer "Sharon, Lois, and Bram" rather than "Sharon, Lois & Bram"

Use the Oxford comma — when you have a list of items, it's the comma that comes before the "and".

• Bad: I'd like to thank my parents, Rick Ross and Jay-Z.
• Good: I'd like to thank my parents, Rick Ross, and Jay-Z.

See also the list of complex adjectives, which use commas in special ways.

Use a space on either side. Get over it, Robyn.

To type an em dash, press option-shift-minus.

• If the lead-in statement is a full sentence, end it with a colon. If it's a fragment, don't add any punctuation at the end. If it is a question, as in a multiple choice scenario, end it with a question mark.
• If the lead-in statement is a full sentence, capitalize the first word in each answer, since the bullet is its own independent statement. If the lead-in statement is a fragment, each bullet point should complete that fragment, and so would not be capitalized.
• End each answer, even if it is a sentence fragment, with normal terminal sentence punctuation.
• Very short answers (eg: True, False, Valve 10, Open) may omit the punctuation.

Abbreviations are always capitalized. For instance, NO and NC (normally-open and normally-closed). Note that we do not use periods between the letters, following Eaton Vickers' example. Remember, unless there is an exception, treat abbreviations as though they are the complete word they are standing in for.

Units are not abbreviations, and have their own rules.

There are two kinds of adjectives: coordinate adjectives, and cumulative adjectives.

Coordinate adjectives individually modify the noun — words like red, hot, big, empty. You can put commas or "and" between them without changing the meaning (though there are certain arrangements that feel worse or better). A heavy, bulky box could just as easily be a bulky, heavy box or even a heavy and bulky box. It's all the same thing.

Cumulative adjectives combine with the noun in a deeper way. You can't add commas or rearrange cumulative adjectives without changing the meaning. When you have a piston pump the word piston is a cumulative adjective. So if you had a red piston pump, you can't rearrange that to a piston red pump without changing the meaning.

When putting adjectives together, if one adjective modifies another adjective (rather than modifying the noun), you sometimes need to use a hyphen. For example, a positive-displacement pump has a hyphen, because positive modifies displacement, not pump. Sometimes you need to stack these adjectives together. This gets very complex, so rather than going off the deep end with rules and exceptions, we'll just capture examples here:

Here's a list of complex adjectives and how we punctuate them:

• fixed-displacement pump
• variable-displacement pump
• positive-displacement pump
• nonpositive-displacement pump
• positive, fixed-displacement pump (pos/non first, then fixed/var)
• nonpositive, variable-displacement pump

Hyphens should never be interchanged with dashes (hyphens are shorter than dashes) and should never have spaces around them.

Words/phrases that are NOT hyphenated:

• Bidirectional
• Buildup (This is a single word when used as a noun or adjective, and two words when used as a verb. Noun: Static buildup can damage sensitive electronics. Verb: Avoid the build up of static electricity.)
• Closed center / open center / tandem center
• Closed loop / open loop
• High voltage
• Pressure compensated / pressure compensating
• Quick coupler
• Subcircuit
• Load control
• Counterclockwise

Words/phrases that ARE hyphenated:

• Cross-port relief valve
• Direct-acting relief valve
• Electro-hydraulic
• High-low circuit
• Hop-over
• Lead-free solder
• Meter-in / meter-out (see also the capitalization rule below)
• Normally-closed / normally-open
• Pilot-operated (also roller-operated, lever-operated, etc. You get the idea.)
• Pre-charge
• Solenoid-controlled
• Spring-loaded
• Load-lowering, load-holding
• multi-stage

See also the list of complex adjectives, which use hyphens in special ways.

If you are using a hyphen in a title, treat each word in the hyphenation by the normal rules of title capitalization.

Special Exception - Capitalize both words in "Meter-In", for symmetry with "Meter-Out".

Capitalize words at the beginning of a sentence, unless those words are specifically intended to be lower case. Words that are not usually capitalized, but are not intended to be lower case, should still be capitalized. Example: Van Gogh's painting was stolen. (Usually written "van Gogh", but ok to write "Van Gogh" at the beginning of a sentence.) However, e.e. cummings' name is expressly not supposed to be capitalized, so don't capitalize it, even to start a sentence. "E.g." is not like that, though, and so it is correct to capitalize the first word/initial.

BUT, try to write sentences so as to not stick "E.g." at the beginning. Might be better to write "Example", instead. Never begin a sentence with e.e. cummings.

For most things, we use the American spelling. Let the following lists guide you through the words and spellings to adopt or avoid.

• Adaptor
• Aluminum
• Analog
• CAN bus (bus isn't part of the proper noun and so does not normally get capitalized.)
• Center
• Color
• Gauge
• LEDs (plural)
• Incompressible

• Inflamable
• Irregardless
• LED's (unless it is possessive, not plural)
• Uncompressible

These two words tend to be used interchangeably. To avoid confusion, we have adopted the following house style:

• When talking about Hydraulics, we call them systems
• When talking about Electrical, we call them circuits

• Electrohydraulics (as per Festo)
• Onboard (specific usage - "Proportional directional valves with onboard electronics" as per Eaton. Other usages might still be two words. )
• Flow meter
• Swash plate (as per Eaton, Bosch Rexroth and Danfoss documents.)
• Load sense
• Work Port (As per Parker Hannifin catalog. They also capitalize it as a proper noun, so we should too.)

Large numbers can be separated into groups of 3 by spaces, as per SI and ISO 31 conventions. Example: 123 456 789

House Rules

• 4 digit numbers should be left without a space, to avoid widowing the leading digit. Example: 1234, rather than 1 234.
• Decimals are exempt from spacing. Example: 12 345.123456

Be sure to code space-separated numbers to avoid line breaks. The recommended pattern is <span class="formula">123 456.789</span>

For easy copy-pasting. You can also find most of these symbols using the macOS character picker Command-Control-Space

• Multiplication: ×
• Division: ÷ (Option-/)
• Root: √ (Option-v)
• Exponentiation: use x<sup>2</sup> to get x²
• Plus-minus: ± (Option-Shift-=)
• Degree: ° (Option-Shift-8)
• Omega / Ohm: Ω (Option-z)
• Diameter (slashed "O", or monophthongl closed midfront rounded vowel for the precise): ø, Ø (Option-o or Option-Shift-O for uppercase)

The rules for writing units are a bit brutal. Here's a quick table (please help expand this).

Name	Symbol	System
gallon	gal	US or Imperial
gallons per minute	gpm	US or Imperial
kilometers per hour	km/h	Metric
liter	L	Metric
liters per minute	L/min	Metric
meter	m	Metric
meters per second	m/s	Metric
pascal*	Pa	Metric
kilopascal*	kPa	Metric
pound	lb	Imperial
pounds per square inch*	psi	Imperial
revolutions per minute	rpm, RPM, r/min	N/A
Volts	V	SI (Metric)
Volts (DC)	DC 12 V	SI (Metric)
Hertz	Hz	SI (Metric)

* The zero reference, when needed, is written behind the unit in brackets. Examples: 10 psi (abs), 37 Pa (abs), 2 psi(diff), 6 kPa (diff). It is not noted by appending a or d to the unit.

Beware of ambiguity between US gallons and UK gallons (also known as Imperial gallons). In many cases it doesn't matter which one we're referring to, since we mostly use relative or abstract quantities. But when dealing with math formulae (like the nomograph) the difference matters a lot.

If you need to convert from psi to bar, use 14.504. Carl and Mark have agreed on this as our standard, instead of the traditional 14.7, after consulting with some other SMEs.

The symbols are the same whether singular or plural — don't add an "s".

Symbols are case-sensitive, names are not.

When placed at the start of a sentence, you may capitalize the first letter of the name of a unit. You may not capitalize the symbol — rewrite the sentence so that the symbol does not come at the start.

The one case where it's acceptable to adjust the capitalization of symbols is when writing in ALL CAPS, such as on a schematic.

There should be a space between a value and its unit. Examples: 10 Ω, DC 6 V, 22 ºF, 10 ºC

The one known exception is the degree symbol when talking about an angle, which does not have a space: 5º

Note to Ivan — you should review this file from Frink and consider building something like it. You can reach out to Alan via FoC if need be.

• BIPM — this is the official standards body that oversees the Metric system.
• Grammar Girl: Units of Measure
• Wikipedia: SI Base Units
• Wikipedia: SI Derived Units