Translations:Documentation/DocumentationTeamInfo/StyleGuide/8/en

From The Document Foundation Wiki
Jump to: navigation, search

The following list summarizes our preferred writing style. Some of these points are discussed in more detail in the tips for writers, reviewers, and editors below.

  • Use short, simple, easy-to-understand words and sentences. Be concise and clear. Ideally:
    • Paragraphs should be no more the six sentences long.
    • Sentences should only contain a maximum of 20 words, with the occasional sentence up to 25 words.
  • Write in active voice or the imperative, using passive voice only when necessary or appropriate. For example, Do this, then do that. A case of appropriate passive voice is when the focus of the sentence is on the receiver of an action whose doer is obvious or is not important. For example, The File dialog is displayed.
  • Use the present tense, using future tense only when necessary or appropriate. Try to make your descriptions timeless. For example, write The File dialog is displayed, rather than The File dialog will be displayed. Use future tense only when one event is necessarily later than another. For example, If you use styles, your documents will be easier to maintain.
  • Avoid the third person, for example phrase the user. Use second person (you) or the imperative.
  • Avoid over-using you. For example, instead of saying if you want to have table headers repeat on a new page, you need to do yyy, say to have table headers repeat..., do yyy.
  • When appropriate (as in instructions), use the imperative. For example, instead of you should not use slang, say do not use slang.
  • In circumstances where the only alternative to you is the passive voice, use you. For example, instead of in this window xxx can be done, say in this window you can do xxx.
  • Use gender-neutral language, but don’t use awkward phrases like he or she to do so. See page 8 for some examples.
  • Avoid using the possessive apostrophe (for example Peter’s). Rewrite the sentence to remove the need for a possessive apostrophe.
  • Do not use contractions of words (for example: don’t becomes do not; won’t becomes will not, and so on).