: Re: Starting a sentence with the name of a program or command-line tool: capitalization? Say you want to talk about a piece of command-line software, like make or bash or the cp command. These

@Hamaas631

Vote Up Vote Down

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".

(0)

Login to post a comment!