Manual Entry Guidelines

The technical writer's requests

Here's a list of requests, of things to do right when you modify the manual.

  1. Make a local copy, and look at your changes before commiting! Do not make someone else fix your Sphinx/rST boo-boos.
  2. Run a spell checker over your changes before committing. The most common spelling errors (in our manual) run two words together as one. "Filesystem" is correctly "file system." "Filename" is correctly "file name." The noun "setup" (as in "My setup is foo bar!") is one word, so please continue using it as one word. As a verb, the two-word phrase is to "set up".
  3. Do not use contractions! They are difficult for readers that do not have English as their first language.
  4. Use spaces instead of tabs.
  5. When making small changes, please do not change the locations of already existing line breaks. Removing the line breaks makes it more difficult for others to later identify and check the modifications.
  6. If you remove or change a label definition, it is your job to check all other parts of the manual to make sure that there are no references that depend on the label.

Here is a list of things that make your technical writer's job easier.

  1. Place line breaks at the end of sentences and phrases. Yes, this makes the file longer in terms of line numbers. But, it also makes editing easier, since changes are often made at the granularity of sentences.
  2. If possible, write using the present tense, with an active voice (not passive voice), and in the third person.
    • Active voice says "after the job executes" where the passive voice "after the job has executed" means the same thing.
    • "You" and "Your job" are examples of second person; third person examples are "the user that submits a job" and "the job."

on Word Choice

Several new terms have come into common usage when we talk to each other. However, some of these terms are not real words, and others are improperly used. Here are two examples that your technical writer continually removes from the manual (so stop using them!).

  • config is not a word. If you think you want to use this term, then instead use configure if you wanted a verb, or use configuration if you wanted a noun.
  • deprecate has cult-following status among those who use it. Unfortunately, the dictionary defines it with "to express disapproval of" or "depreciate."
    • Karen deprecates the use of the word "deprecate". is a correct usage.
    • Karen desperately wants to deprecate the word "deprecate" from the manual. is an incorrect usage.