Documentation Style Guide

Documentation contributions should uphold the following style rules.

Voice

Write as an expert on the software, rather than one of its maintainers. This encourages contributions. For example, instead of “we decided to change…”, use “Workarea 3.3 changes…”.

Titles & Headings

The title of each document and the heading of each document section should describe either a concept or the procedure to complete a task. Use nouns for titles and headings that represent concepts. Use verbs to represent tasks.

Capitalize the first word and important words.

Examples (concepts):

  • Content
  • Plugins
  • Orders & Items
  • Placing Orders

Examples (tasks):

  • Add System Content
  • Release a Plugin
  • Export Orders
  • Place an Order

Try to limit outline depth to three levels (h1-h3). If you find yourself needing a deeper outline, consider re-organizing the content into multiple documents.

Proper Nouns

Names of software packages, such as Admin and Storefront are proper nouns, which are capitalized.

Names of features are not proper nouns and are not capitalized. Examples:

  • cart
  • checkout
  • Admin toolbar

Spelling & Grammar

At this time there are no prescribed style rules regarding spelling, grammar, and language. However, always use a spell checker before submitting contributions.