HTCondorWiki: Manual Entry Guidelines

Page History

The technical writer's requests

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

Make a local copy, and look at your changes before commiting! Do not make someone else fix your LaTeX boo-boos.
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".
Do not use contractions! They are difficult for readers that do not have English as their first language.
Use spaces instead of tabs.
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.
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.

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

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.

Configuration macro names are identified with one of two LaTeX macros. \Macro{} automatically generates an index entry within the manual. \MacroNI{} does not generate an index entry. NI stand for No Index. When deciding which to use, err on the side of including too many index entries. But, if you use the macro's name more than once within the same paragraph or subsection, use \Macro{} the first time, and then use \MacroNI{} for the remainder. We do this so that we do not get multiple independent index entries pointing to the same paragraph. The LaTeX indexing tools do not collapse multiple entries for us.
ClassAd names (both job and machine ClassAd names) are identified with \AdAttr{}.

misc

Font size for verbatim examples. Our examples within the manual that use a fixed-width font start and end with a
```
        \begin{verbatim}
        \end{verbatim}
```
To insure that the pdf and postscript versions of the manual do not cut off the ends of the longer lines, reduce the font size. Add two more LaTeX macros surrounding the example, such that the source appears as
```
        \footnotesize
        \begin{verbatim}
        The long line(s) of verbatim text here.
        \end{verbatim}
        \normalsize
```
What constitutes a "longer line" is debatable. Definitely include it for lines that have more than 60 characters, but err on the side of safety (nice pdf output) by adding this for all but the shortest (20 characters or less). The goal of this advise is that you (the developer) will not need to examine the pdf output to check for lines that get cut off.