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 LaTeX 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 techical 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 editting 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!).

Use of LaTeX macros

For consistancy in our formatting throughout the entire manual, please use our LaTeX macros. The main set of macros is in the file condor-macros.tex. When trying to decide what (if any) LaTeX macro to use, attempt to use these as already used in other parts of the manual.

A big no-no is to introduce your own LaTeX macro within whatever file you are working on. If you really need a new macro defined, place it in condor-macros.tex.

Here are some common uses.