12.2. Guidelines
Prev | Chapter 12. Writing Style | Next

## 12.2. Guidelines

To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow.

Use American English Spelling

  There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. “color”, not “colour”, “rationalize”, not “rationalise”, and so on.

  ### Note:

  The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. will have to use American English.

Do not use contractions

  Do not use contractions. Always spell the phrase out in full. “Don't use contractions” would be wrong.

  Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators.

Use the serial comma

  In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word “and”.

  For example, look at the following:

  > This is a list of one, two and three items.

  Is this a list of three items, “one”, “two”, and “three”, or a list of two items, “one” and “two and three”?

  It is better to be explicit and include a serial comma:

  > This is a list of one, two, and three items.

Avoid redundant phrases

  Try not to use redundant phrases. In particular, “the command”, “the file”, and “man command” are probably redundant.

  These two examples show this for commands. The second example is preferred.

  Use the command `svn` to update your sources.

  Use `svn` to update your sources.

  These two examples show this for filenames. The second example is preferred.

  … in the filename `/etc/rc.local`…

  … in `/etc/rc.local`…

  These two examples show this for manual references. The second example is preferred (the second example uses `citerefentry`).

  See `man csh` for more information.

  See csh(1).

Two spaces at the end of sentences

  Always use two spaces at the end of sentences, as this improves readability, and eases use of tools such as Emacs.

  While it may be argued that a capital letter following a period denotes a new sentence, this is not the case, especially in name usage. “Jordan K. Hubbard” is a good example; it has a capital `H` following a period and a space, and there certainly is not a new sentence there.

For more information about writing style, see Elements of Style, by William Strunk.

Prev | Up | Next
Chapter 12. Writing Style | Home | 12.3. Style Guide

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.