This page is an attempt to standardize some of the terminology and phraseology that we use in the RHEL documentation. Don't consider this as the final word by any means, but a set of guidelines.
Glossary
Asks for
Use "requests" instead.
By way of
Use "using" instead.
Examples:
connect one desktop or workstation to another by way of a host-to-host connection (incorrect)
connect one desktop or workstation to another using a host-to-host connection (correct)
For further/additional/whatever information
Use "For more information"
For instance
Use "For example"
For this reason
Use "therefore"
Gerunds
Everybody's favourite topic. The following is just an example of how it has been used, how it could be confusing, and how it could be improved:
For instructions on constructing iptables rules... Could be read as "how to get instructions while you're constructing iptables rules" (parallel operation)
For instructions on how to construct iptables rules... Less confusing
Giving Command Examples
Include a basic shell prompt, either for a normal user or for root, as appropriate.
Don't include the path unless it seems absolutely necessary. (Note: this refers to commands, not files.)
If you have two commands immediately following each other, they look better (in html at least) if they're contained in the same tag. i.e., don't have a pair for each command.
Try to use sensible names, or at least names that aren't confusing...
Examples:
[root@myServer ~ ] # chkconfig --level 345 iptables on
Lots of
Use "Several" or something equivalent instead.
Plurals
Dont's put "es" in parentheses to indicate plurals. I try to use this line of thought:
If it can only be singular, leave it singular
If it can be plural, make it plural
Examples:
Bind the IP address(es) to the appropriate port(s)
Bind the IP addresses to the appropriate ports
Sentence Syntax and Example Formats
The most common example I have come across is the way we use "Refer to xxx for more information". Sometimes it is written "For more information, refer to xxx", with other variations scattered around the place.
Technical Syntax
Functions
Take parameters and use syntax
Examples:
The myFunction() function takes the following parameters:
The myFunction() function uses the following syntax:
struct definitions
Contain fields and use syntax
Examples:
The ldapmod struct definition contains the following fields:
The ldapmod struct definition uses the following syntax:
Tells
Use "instructs", or "informs" instead, depending on the context.
Examples:
This option instructs the command to process all files in alphabetical order.
Within
Don't use to refer to a file that exists in a directory. Use "In".
Examples:
If the iptables file exists within the /etc/sysconfig directory... (Incorrect)
If the iptables file exists in the /etc/sysconfig directory... (Better)
If the /etc/sysconfig/iptables file exists, ... (Even better)
