Writing style

This section describes general writing style guidelines that documentation contributors should follow to ensure consistency throughout all technical publications.

• General writing guidelines
  • Use standard English
  • Write in active voice
  • Use the present simple tense
  • Write in second person
  • Use appropriate mood
  • Keep sentences short
  • Avoid ambiguous titles
  • Be clear and concise
  • Write objectively
  • Describe the most common use case first
  • Do not humanize inanimate objects
  • Write positively
  • Avoid prepositions at the end of sentences
  • Do not overuse this, that, these, and it
  • Do not split infinitives
  • Avoid personification
  • Do not use contractions
  • Eliminate needless politeness
  • Use consistent terminology
  • Use spelling and grammar checking tools
• Word choice
• Punctuation
• Headings
  • General guidelines
  • Section titles
  • Subsection titles
  • Topic titles
  • Figure and table titles
• Lists
  • Punctuation in lists
• URLs
• Numbers and units of measure
• Naming convention
  • Using OpenSDNs full name and abbreviation
  • Upper- and lowercase in OpenSDN’ service and modules names
• Release names
• Standard UI terminology
  • Command-line interface guidelines
  • Web user interfaces guidelines
• Code conventions

This documentation, is a derivative of Writing style by OpenStack, used under CC BY.