5 Golden Rules of Capitalization in Software Documentation

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?

Get MS Office and Apple iWork templates

Acceptance Test Plan

Contingency Plan

Software Development Templates

Acquisition Plan

Conversion Plan

Software Requirements Specification

Action Plan

Cost Benefit Analysis

Software Testing

API Documentation

Database Design

Standard Operating Procedures (SOP)

Audience Analysis

Datasheet

Statement of Work

Availability Plan

Deployment Plan

System Administration Guide

Bill of Materials

Design Document

System Boundary

Business Case

Disaster Recovery Plan

System Design Document

Business Continuity

Disposition Plan

System Specifications

Business Plan

Documentation Plan

Technical Writing Templates

Business Process

Employee Handbook

Test Plan

Business Requirements

Error Message Guide

Training Plan

Business Rules

Expression of Interest

Transition Plan

Capacity Plan

Fact Sheet

Troubleshooting Guide

Case Study

Feasibility Study

Use Case

Change Management Plan

Functional Requirements

User Guide

Communication Plan

Grant Proposal

Verification and Validation Plan

Concept of Operations

Implementation Plan

White Papers

Concept Proposal

Installation Plan

Work Instructions

Configuration Management Plan

Interface Control Document

Software Development Templates

Acceptance Test Plan

Maintenance Plan

Software Requirements Specification

Acquisition Plan

Market Research

Software Testing

Action Plan

Marketing Plan

Standard Operating Procedures (SOP)

API Documentation

Needs Statement

Statement of Work

Audience Analysis

Operations Guide

System Administration Guide

Availability Plan

Policy Manual

System Boundary

Bill of Materials

Project Plan

System Design Document

Business Case

Proposal Manager Templates

System Specifications

Business Continuity

Proposal Template

Technical Writing Templates

Business Plan

Quality Assurance Plan

Test Plan

Business Process

Release Notes

Training Plan

Business Requirements

Request for Proposal

Transition Plan

Business Rules

Risk Management Plan

Troubleshooting Guide

Capacity Plan

Scope of Work

Use Case

Case Study

Security Plan

User Guide

Change Management Plan

Service Level Agreement (SLA)

Verification and Validation Plan

Communication Plan

Setup Guide

White Papers

Concept of Operations

Social Media Policy

Work Instructions

Concept Proposal

Contingency Plan

 

Configuration Management Plan

Conversion Plan