Writing Style Guidelines

Table of Contents: Guidelines | Tips and Tricks | References | Related Links

Guidelines

Guidelines are suggestions. They are not rules.

Don't worry about perfection. Try to do your best the first time around, to prevent creating work for others, but remember:
- The content is the most important thing.
- If there a mistake, it can be corrected later.
- The grammar or writing style can be upgraded later.
Be bold.
Use a positive tone.
- Be upbeat and friendly in your writing style.
- Two excellent examples of negative topics discussed with a positive tone are
  1. the escapers page
  2. the tilde page
When you are finished, read your content carefully to make sure that it says what you want it to say.
- Read it as if you were somebody else reading it for the first time.
- Read it from the point of view of a person whose vocabulary is limited, from the point of view of a non-native speaker.
- For this reason, avoid idiomatic expressions.
  For example, write "Clarity is the most important goal in writing," rather than, "Clarity in writing is the golden rule, and 'way cool,' too."
- Read it again at least a week later to see if you want to change anything.

Tips and Tricks

Feel free to use the singular they. (The "singular they" avoids bringing up the potentially controversial "woman's rights" issue.)
Here are two examples. The first uses the "singular they", the second does not. Both styles are considered acceptable.

1) "If you take black, then you will move first; your opponent will take white; and they will move first."
2) "If you take black, then you will move first; your opponent will take white; and she will move first."

The "singular they" works best when the referent is an indefinite person. For example, the "singular they" works well in the sentence, "If someone jumps into a lake, then they will get wet." It does not work as well when the referent is a definite person. For example, the "singular they" does not work at all in the sentence, "If Pat O'Keeffe jumps into a lake, then they will get wet."
When a direct quote finished at the end of a sentence, put the period inside the quote if it logically belongs there. For example, it the quote is a full sentence, the final period usually belongs before the final quotation mark. A good rule of thumb is "When it doubt, put it out."
--- This is the modern school of thought on this issue. The old school said, "If you put it in, you'll always win." This is one reason why the previous generation had trouble when hyperlinks came along.
Another good rule of thumb regards the use of capital letters. "When in doubt, leave it out."
--- This is another example of the evolution of grammar in American English.
Use quotation marks or hyphens to group adjectives that belong together. This helps eliminate ambiguity.
--- Example: "The dark-blue fox jumped over the lazy white cat."
This basic principle applies to phrases too.
--- Example: "Italics and parentheses are used to set off ready-to-be-implemented change notes when it is clear how the implementation should proceed."
Use initial caps for the significant words in a title. The titles in the Hot Links list are an exceptions to this guideline. Only the first word in each title has an initial cap.
Put the title of a help page in quotes if you want to make it stand out even more than the initial caps do. If the quotes are not enough, use bold. Bold is usually better than quotes to make things stand out, anyway. This is even more true for acronyms. Put long titles in quotes to group the words together.
- Titles are not normally enclosed in quotes.
The guideline concerning putting titles in quotes (as opposed to putting them in bold) also applies to the names of buttons.
Put a comma before a direct quote. This helps distinguish quotation marks that are used to enclose direct quotes from other uses of quotation marks.
--- Example: Write, "Please do it as soon as you are ready", rather than, "Do it when it is convenient for you."
It is often possible to refer directly to a page, as opposed to putting "the" before the page-title and "page" after it.
--- Example: Write, "There are a lot of change notes in Future Editing Plans", rather than, "There are a lot of change notes in the Future Editing Plans page."
Avoid using the future tense, even when talking about events in the future.
- For example, say "The next version is expected to be released in 2011", rather than, "It is expected that the next version will be released in 2011."
Avoid using the past tense, except in a narrative.
- The change logs and the Recent Events are two examples of narrative text.
- For example, say "After completing the first task, ..", rather than either "After you have completed the first task, .." or "After having completed the first task, .."

References

If you would like references for English grammar and style, here are four good ones.

"The American Heritage Dictionary of the English Language" 4th edition
"The Secretary's Handbook" for grammar and word usage
"The Elements of Style" by Strunk and White for writing style
"Technical Writing Style"