Post History

Source: https://writers.stackexchange.com/a/23433
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Rule #1 in technical documentation is: don't mislead the reader. If the command or function name begins with a lowercase letter, capitalizing it is an error -- it's not "Cat" but "cat". The _Microsoft Manual of Style_ specifies that literal elements like this should be written with their correct case. It also calls for using text styling to offset them, as do other style guides I've used. (Microsoft favors bold; others favor monospace.)

Surprisingly, software-oriented style guides in my experience don't address the specific case of beginning a sentence with these items. If you can write around the problem _without making the documentation more cumbersome_, I've found it's best to do that. Instead of

> `cat` is a Unix utility for concatenating files.

You might be able to write

> Use `cat` to concatenate files.

You could write

> The `cat` utility concatenates files.

However, this can quickly become either cumbersome or inconsistent -- if you say "the `cat` utility" in some places but "`cat`" in other places, you leave readers wondering why. But if you use the former formation everywhere, you make the documentation harder to scan and add extra words seemingly needlessly.

The software-documentation teams I've been part of for the last 20 years or so have all followed this guideline: write around the problem if you can do so reasonably, and if you can't, just start the sentence with the lowercase name. Using text styling for command/function/etc names mitigates the capitalization "error".

Original score: 12