To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow.
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.
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. Always spell the phrase out in full. “Don't use contractions” is wrong.
Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators.
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:
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.
Do not use redundant phrases. In particular, “the command”, “the file”, and “man command” are often redundant.
For example, commands:
Wrong: Use the command svn
to
update sources.
Right: Use svn
to update
sources.
Filenames:
Wrong: … in the filename
/etc/rc.local
…
Right: … in
/etc/rc.local
…
Manual page references (the second example uses
citerefentry
with the
&man.csh.1;
entity):.
Wrong: See man csh
for more
information.
Right: See csh(1).
Always use two spaces between sentences, as it improves readability and eases use of tools such as Emacs.
A period and spaces followed by a capital letter
does not always mark a new sentence, especially in names.
“Jordan K. Hubbard” is a good example. It
has a capital H
following a period and
a space, and is certainly not a new sentence.
For more information about writing style, see Elements of Style, by William Strunk.
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 <[email protected]>.
Send questions about this document to <[email protected]>.