User Guides

5 Golden Rules of Capitalization in Software Documentation

Posted on by Ivan Walsh

How do you spell Yahoo? Most of us spell it like we say it, which is wrong… It’s Yahoo! not Yahoo. Why is this important? From one angle, it isn’t but if you want your documents to look professional, then you need to understand when and where to capitalize words.

Where to start with CapitalizationThe Golden Rules of Capitalization in Technical Documents

How developers use capitalization in their Use Case and User Manuals creates problems for editors, reviewers, and of course users. Or should that be Users?. Part of the problem is a lack of guidelines and style guides.

What you think looks fine break some style guide rule you were unaware of.

My favorite example is Microsoft.

When it started out, it was MicroSoft. Then it changed the uppercase S to a lowercase s.

This creates other problems with legacy documents or international materials, for example, business documents for Japanese readers?

5 Guidelines for Capitalization

In general, use capitalization rules whenever possible – for example, common nouns are usually all lowercase and proper nouns are capitalized.

  1. Never use all uppercase letters for emphasis.
  2. Follow the capitalization rules of software as necessary, as in case-sensitive keywords.
  3. Do not capitalize the spelled-out form of an acronym unless specified otherwise.
  4. Avoid over-capitalization.
  5. Check the Style Guide.

Capitalization in the User Interface

Microsoft recommends the following capitalization rules for interface elements:

  • Menu names, command and command button names, and dialog box titles and tab names: Follow the interface. Usually, these items use title caps. If the interface is inconsistent, use title caps.
  • Dialog box elements: Follow the interface. Newer style calls for these items to use sentence caps. If the interface is inconsistent, use sentence caps.
  • Functional elements: Capitalize the names of functional elements that do not have a label in the interface, such as toolbars (the Standard toolbar) and toolbar buttons (the Insert Table button).
  • Do not capitalize interface elements used generically, such as toolbar, menu, scroll bar, and icon.
  • The Golden Rules of Capitalization in Technical Documents Do not capitalize unless it is case-sensitive.

Other examples

When it comes to caps – or should that be capitalization – I see these everywhere.

For example:

Is it web site or Web Site or Website?

Is it the Bible of The Bible?

The Day of the Jackal or The day of the Jackal

What Color Is Your Parachute?  or What Color is your Parachute?         

A Tale of Two Cities or A Tale Of Two Cities

What other examples can you think of?

Ivan Walsh