Capitalization

IMPORTANT: This topic is about capitalization. However, all of the following examples contain discussions of multiple subjects—not just capitalization. Therefore, in addition to capitalization, you are going to learn a lot of different things about good writing and rewriting.

Example 1

REWRITE THESE SENTENCES

PROBLEM

These words should not be capitalized:

  • business unit
  • suppression list
  • server
  • token generation
  • taxonomy
  • cached guest data
  • session

DISCUSSION

Why Capitalization Should be Kept to a Minimum

Do not capitalize any more than is absolutely necessary. Use lowercase unless there is a specific reason for uppercase.

There are two reasons why we want to minimize capitalization.

  • Excessive capitalization impairs readability. Unnecessary capitalization makes text more difficult to read. When text is difficult to read, users have a tendency to skip hard-to-read passages, skim the text, or quit reading entirely. You want to avoid these outcomes.
  • Excessive capitalization can be a problem with localization. If there is excessive capitalization, in-house translators or vendors might need more time for translations.

When We Capitalize

We capitalize:

  • Proper names
  • Specified product names
  • The feature or technology name if there is a marketing or branding campaign around the name

When We Do Not Capitalize

We do not capitalize:

  • General references to ordinary software tools
  • General references to an area on the user interface—not to the specific UI feature
  • General references to a software process—not to the specific process that might have a formal name

Why the Following Words Are Not Capitalized

  • business unit—This a general reference to a business unit.
  • suppression list—We are talking generally about the suppression list as part of an overall process description. We are not referring to a specific suppression list, nor are we talking about the words suppression list as a specific feature on the user interface. Thus, suppression list is all lower case in this sentence.
  • server, token generation—EVA is a type of software. It is an actual product name, The word server is not part of the product name; therefore, it is lower case. Do not capitalize token generation. In this sentence, we have a general reference to the process of token generation.
  • taxonomy—Basically, a taxonomy is a way to group things together. In this sentence, the word taxonomy is not capitalized because it is not a proper name and it is not a specific product name. It refers to the concept of taxonomy.
  • cached guest data, session—We have a general reference to the cached guest data. This is not a proper name or a product name. The word session is not a proper name or a product name in this context. It should be lower case.

REVISIONS

Before

The following section provides most of the information you need for the service used by your Business Unit (BU).

FakeCorp maintains a Suppression List containing the email addresses of users who indicate they don’t want to get any more promotional email from a particular line of business.

EVA Server mediates the communication with AuthenticationPlus in the case of Token Generation.

Defining the correct metrics enables us and the BU to measure and track use of the service according to the Taxonomy, which in turn supports the ongoing management of the service.

The refresh also updates the Cached Guest Data in in the CorpID Session.

After

The following section provides most of the information you need for the service used by your business unit (BU).

FakeCorp maintains a suppression list containing the email addresses of users who indicate they don’t want to get any more promotional email from a particular line of business.

EVA server mediates the communication with AuthenticationPlus in the case of token generation.

Defining the correct metrics enables us and the BU to measure and track use of the service according to the taxonomy, which in turn supports the ongoing management of the service.

The refresh also updates the cached guest data in in the CorpID session.

REMARKS

The style rules for capitalization in software documentation are rarely understood by the persons who author most of the initial documentation—the computer programmers and software engineers. Since they do not understand the industry-accepted guidelines for capitalization, these authors have a lamentable tendency to over-capitalize. If the software tool, product, or process is important, it probably warrants capitalization.

A lot of engineers take this approach: When in doubt, make it upper case.

People not versed in the rules of documentation style tend to capitalize things they think are important. For example, if you are sending your kids to college because you spend years of your life working on a software tool called suppressionlist, you might think it is reasonable to call it Suppression List.

Then there is pride of authorship. Now that you decide Suppression List is appropriate, you might not appreciate some English major telling you it is incorrect. Consequently, the technical writer, who comes late to the party, may face stiff resistance when enforcing industry standards about capitalization.

Writers and editors—my advice to you is to enforce the industry standards to the best of your ability, but do not go to war over capitalization. It’s not worth it. Pick your battles. No one ever died because a word was incorrectly capitalized or incorrectly made all lower case.

Example 2

REWRITE THIS SENTENCE

PROBLEM

The word boolean is all lower case.

DISCUSSION

Boolean should always be initial-capped because it is named after a person, the English mathematician George Boole.

There is an exception to the rule in software documentation. When you refer to the data type Boolean as it appears in a specific line of code, and the actual word in code is all lower case, do not capitalize it. Often the referenced word Boolean is set in Courier font in the text to distinguish it from the other words.

REVISION

Before

In most computer programming languages, a boolean data type is a data type with only two possible values: true or false.

After

In most computer programming languages, a Boolean data type is a data type with only two possible values: true or false.

Example 3

REWRITE THESE SENTENCES

PROBLEM

There is nothing wrong with these three sentences. You do not need to rewrite anything.

Oh, wait. Did you notice the two words in all upper case letters, IF and NOT? Do you feel someone is shouting at you?

DISCUSSION

Most style guides frown on the practice of using all caps for emphasis. Use italic type.

REVISION

Before

The error_description is the data block that comes with the error.  IF it is appropriate, this block usually contains a guest object.  If it is NOT appropriate, this data block contains appropriate information to fix the error.

After

The error_description is the data block that comes with the error.  If it is appropriate, this block usually contains a guest object.  If it is not appropriate, this data block contains appropriate information to fix the error.

Example 4

REWRITE THESE SENTENCES

PROBLEM

We capitalize the feature or technology name if there is a marketing or branding campaign around the name. Otherwise, do not initial-cap ordinary software tools.

DISCUSSION

In the first example, the token validation filter and the token scope filter are just tools and don’t merit initial caps. Both terms should be all lower case.

In the second example, Awesome Technologies has a device called the FakeApp Server. You see the marketing language in the first part of the quote. The word Server is capitalized for branding reasons. Much later in the document (after the ellipses), the author describes the actions of the FakeApp server. At this point, we are talking about a software tool.

Technical writers and technical editors must understand the rules for capitalization and enforce those rules. Some engineers love to capitalize their nouns. Don’t let them get away with it.

Capitalization can be a big issue for localization as translators and international editors are forced to clean up excessive capitalization for their target audiences. It’s an unnecessary waste of your company’s time and money.

REVISIONS

Before

Both filters should be added to your service, with the Token Validation Filter handling the request first, and then passing it on to the Token Scope Filter.

Awesome Technologies has upgraded the capabilities of the FakeApp Server … If the FakeApp Server successfully validates the assertion, the response is the standard authorization response, including a refresh token.

After

Both filters should be added to your service, with the token validation filter handling the request first, and then passing it on to the token scope filter.

Awesome Technologies has upgraded the capabilities of the FakeApp Server … If the FakeApp server successfully validates the assertion, the response is the standard authorization response, including a refresh token.

Example 5

REWRITE THIS SENTENCE

PROBLEM

Capitalization in this sentence is a problem. Data Solutions is a brand. It should be capitalized. REST stands for representational state transfer (REST) based communications. It is always all caps.

These words should be all lower case:

  • ingest
  • store and access
  • transform
  • manage

DISCUSSION

The words ingest, store and access, transform, and manage are simply verbs in the infinitive form:

  • to ingest
  • [to] store and access
  • [to] transform
  • [to] manage

They should not be capitalized.

Also, we need to replace the Latin phrase via with by using.

REVISION

Before

Data Solutions is a set of services that allows users to Ingest, Store and Access, Transform, and Manage their data via a set of REST APIs.

After

Data Solutions is a set of services that allows users to ingest, store and access, transform, and manage their data by using a set of REST APIs.

Example 6

REWRITE THIS SENTENCE

PROBLEM

Usage:

utilizing

Capitalization:

id (twice)

Present vs. Past / Perfect Tenses (see the bold type):

If you were utilizing an iPhone app, the delivery profile would be the device id combined with an app id.

DISCUSSION

Don’t use utilizing or utilization if you can avoid it. The words use (verb) and use (noun) or usage (noun) mean the same thing.

ID is the correct abbreviation for identification.

Instead of saying if you were, say if you are. Instead of saying the delivery profile would be, say the delivery profile is. Avoid the perfect tense. Use the present tense.

REVISION

Before

If you were utilizing an iPhone app, the delivery profile would be the device id combined with an app id.

After

If you use an iPhone app, the delivery profile is the device ID combined with an app ID.

Example 7

REWRITE THESE SENTENCES AND THE BULLET LIST

PROBLEM

Fix these problems:

  • Can do something
  • Capitalization
  • Latin phrases
  • Parallelism
  • Passive voice
  • Punctuation
  • Usage
  • Word order

DISCUSSION

Can Do Something

Don’t say this:

A Feature Gap can be anything….

Say this:

A Feature Gap is anything….

Capitalization

In the FakeCorp software documentation, it is clear that the phrases feature gap and feature request are not product names, nor are they phrases belonging to a larger branding campaign of FakeCorp Marketing. The words are ordinary software terminology. There is no reason to make these words initial capped. Leave both phrases all lower case.

Also, the word legal does not need capitalization in this instance because it a generic reference to legal requirements, not to the Legal department.

Latin Phrases

Never use the Latin phrase e.g. and the Latin phrase etc. together in the same context!

Parallelism

The bullet list does not have parallel grammatical construction. Don’t say this:

    • Will take
    • Requires
    • Requires

Say this:

    • Takes
    • Requires
    • Requires

Passive Voice

Don’t say this:

DISDKANs are logged….

Say this:

Log the DISDKANs….

Punctuation

Make these fixes:

  • Remove the quotation marks from DISDKAN
  • Add a comma after e.g.
  • Add a period after etc

Usage

When you build a bullet list, don’t end bullet items with ; or. Just write the bullet items—with no end punctuation, if possible. However, remember that if one bullet item takes end punctuation, all bullet items must have end punctuation.

Word Order

Don’t say this:

A feature gap is anything that the FakeCorp ID product does not currently support.

Say this:

A feature gap is anything that the FakeCorp ID product does not support currently.

For the word order of currently, there is this exception. If you want to emphasize the fact it is now supported—as opposed to being unsupported in the past—inset the word currently into the middle of the verb form. By breaking up the verb form, you draw attention to the word currently.

REVISION

Before

A Feature Gap can be anything that the FakeCorp ID product does not currently support. A Feature Request is called a “DISDKAN”. DISDKANs are logged when the Feature meets any of the following criteria:

    • Will take more than 12 hours to complete; or
    • Requires stakeholder visibility (e.g. Legal compliance, business unit feature request, etc); or
    • Requires multiple teams to deliver

After

A feature gap is anything that the FakeCorp ID product does not support currently. A feature request is called a DISDKAN. Log the DISDKANs when the feature meets any of the following criteria:

    • Takes more than 12 hours to complete
    • Requires stakeholder visibility (For example, legal compliance and business unit feature request)
    • Requires multiple teams to deliver

Example 8

REWRITE THIS SENTENCE

PROBLEM

These issues:

  • Capitalization
  • Perfect tenses and present vs. past—these issues are related
  • Usage

DISCUSSION

Capitalization

The phrase business units should be all lowercase. It is not a product name or a proper name.

It is correct to capitalize the word Legal. This is a reference to the corporate Legal department.

Perfect Tenses, Present vs. Past

Don’t say this:

should have gone through

Say this:

should go through

Be direct and use the present tense.

Usage

The word before is preferable to prior to.

On the subject of prior to vs. before, this comes from the Language Usage Weblog:

Today’s first tip is about a controversial phrase, ‘prior to.’ The debate is about whether the phrase is grammatically correct since ‘prior’ is an adjective. As Rhett Butler said, ”Frankly, my dear, I don’t give a damn.” There’s a simple reason that ‘prior to’ should be used only sparingly, and it has nothing to do with grammar and prepositional phrases and the like. It is this: ‘prior to’ is pretentious and wordy. Why use ‘prior to’ when ‘before’ is a perfectly good word just waiting to be used? Lovers of language have this to say about the use of ‘prior to:’

Bill Bryson―There is no difference between the two except length and a certain inescapable affectedness on the part of prior to.

Jack Lynch―For a less stuffy and bureaucratic tone, replace prior to or prior with before or earlier whenever possible.

H.W. Fowler―Previous to and prior to are grammatically blameless, but that does not justify their use as substitutes for before because they are thought to be grander or more genteel.

REVISION

Before

Prior to completing an onboarding request and being approved for onboarding to FakeCorp ID, Business Units should have gone through the READ process with Legal.

After

Before you complete an onboarding request and get approval for onboarding to FakeCorp ID, business units should go through the READ process with Legal.

Example 9

SHOULD THESE JOB TITLES BE CAPITALIZED?

PROBLEM

All three sentences contain job titles:

  • Solutions Engineer
  • President
  • president

Are there any errors in capitalization?

DISCUSSION

From Your Dictionary, here are the basic rules for capitalization:

Rules for Capitalization of Job Titles

The easiest rules to remember are:

    • Capitalize a job title that comes before the person’s name. Example would be: Professor Plum or Reverend Green. The title might give more information, like: Dean of Students Harry Houdini, Speaker of the House Thomas Thumb, or Chairman Scarlett.
    • If the job title comes right after the person’s name then it is capitalized, as in: Sarah Smith, Chairman, will attend the meeting.

In signature lines at the end of a letter or email, the job title would be capitalized, like:

Sincerely,

Mary Contrary, President

If a job title is not preceded or followed by a person’s name, it may still be capitalized, if it is used as a name. For example: “I saw the Prime Minister today.” In this case, it is being used as name and not a general kind of job, as in “We have had eleven prime ministers in this century.”

To summarize the capitalization of job titles, you capitalize the job title when it comes immediately before the name or immediately after the name. It is not capitalized if it comes after the name if there is a “the” before it.

Here are some examples of these rules in sentences:

    • Colonel Mustard killed Mr. Boddy.
    • Professor of Archeology Bill Diggs is looking for Atlantis.
    • Mr. Waters, President of Neverland, will give a speech.
    • Mrs. Butterworth, the chairwoman of Pancakes Anonymous, is retiring.
    • Will Writealot, who was the managing editor, got fired.
    • Did you see the Queen of England at the party?

Another rule of capitalization of job titles concerns abbreviations. Doctor Seuss would be Dr. Seuss and General Grant would be Gen. Grant. So the rule could be: capitalize job titles or abbreviations that come immediately before or after a person’s name.

* * * * * * * * * *

Example Sentence 1 – incorrect

The job title solutions engineer is not capitalized. Why? In this sentence, the job title is simply a generic reference. It is not tied to a specific individual.

Example Sentence 2 – Correct

It is correct to say:

  • President Barack Obama
  • Barack Obama, President

However, the lack of capitalization in this example sentence is correct. The word president should be lower case. Why? Because the phrase African American president is merely descriptive. It does not represent a formal job title.

Example Sentence 3 – Correct

The word president is not capitalized. Why? This is a general reference to those who held the presidential office. Of all those presidents, JFK is the one who actually used the Oval Office for day-to-day work. The other presidents, not so much.

REVISION

Before

Contact your FakeCorp Solutions Engineer for help.

As the first African American president in the long history of the law review, Obama drew widespread media attention and a contract from Random House to write a book about race relations.

The last president to use the Oval Office regularly for desk work may have been John F. Kennedy.

After

Contact your FakeCorp solutions engineer for help.

As the first African American president in the long history of the law review, Obama drew widespread media attention and a contract from Random House to write a book about race relations. [no change]

The last president to use the Oval Office regularly for desk work may have been John F. Kennedy. [no change]