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.
Help Us Improve this Doc
Was this helpful? Open a GitHub issue to report a problem with this doc, suggest an improvement, or otherwise provide feedback. Thanks!