10

Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you capitalize them), and also often double as the names of the software projects that write the programs that the commands invoke. What happens when you want to start a sentence with the name of one of these tools? Which of the following is best?

  • cat is a Unix utility for concatenating files. (Start a sentence with a lower-case letter, which looks weird.)
  • Cat is a Unix utility for concatenating files. (Capitalize the command name, which looks weird and won't run.)
  • cat is a Unix utility for concatenating files. (Start the sentence with one of these weird code box things. Requires that that formatting option be available, and you still end up leading with a lower-case letter.)
  • One Unix utility for concatenating files is cat. (Just write around the problem because you don't know what to do otherwise.)

Do any style guides address this issue?

  • 2
    Good question, I've run into this quite a few times myself and I often alternate between capital and lowercase. – raddevus Jun 18 '16 at 14:55
12

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

7

The GNU site itself treats the name of the Make utility as an uppercased word: https://www.gnu.org/software/make/

There does seem to be a convention to frequently use make (the command) where Make (the name) would seem more appropriate. The GNU Make manual seems to do this almost exclusively (https://www.gnu.org/software/make/manual/make.html) but always with a font change to indicate that it is the command that is being used.

So those examples would justify the second and third options for Make, though the manual seems to avoid using make at the beginning of a sentence.

It is less clear that cp or cat can be treated this way, though. They are commands more than stand-alone products like Make. I'd be inclined to avoid using them as stand alone names and instead use "The cat command" as in:

The cat command is used to concatenate files.

  • 1. Command cat concatenates files. 2. Use cat to concatenate files. – Drew Dec 31 '18 at 17:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.