Style Guide
This page lists provides a no-frills set of editorial and stylistic guidelines.
| Style issue | Usage |
| Code - block | a - Format in monospace font one point size smaller than
running text.
b - Format line breaks so as to preserve the code to copy and paste. c - (Ideally) Upload to our GitHub repo complete, ready to run examples. d - Link to the example set on GitHub. |
| Code - inline | a - Format in monospace font one point size smaller than running text. |
| Names - acronyms | a - Full name with acronym in parenthesis (first mention).
b - Acronym (thereafter). |
| Names - author(s) | a - Place the full name and degree immediately following
publication title.
b - Place the affiliation immediately following author name (optional). |
| Names - elements or attributes | a - Format in monospace font one point size smaller than
running text.
b - Avoid plural forms. |
| Names - files | a - Format in monospace font one point size smaller than running text. |
| Names - products | a - Company and product name (first mention), e.g. Syncro Soft Oxygen Editor.
b - Product name (thereafter). e.g. Oxygen. |
| Names - standards | a - Standards org and standard name (first mention), e.g. OASIS DocBook.
b - Product name (thereafter), e.g. DocBook. |
| Names - user interface elements | a - Bold. |
| Names - variable attribute values | a - Italics |
| Ordered lists | a - Strive for a consistent sentence structure for each
list item, e.g. Context - Ver b - Object - Goal. b - Separate actions (list items) from effects and examples (blocks nested within list items. c - Provide at least a one-sentence introduction preceding the list. Recommended. |
| Person | a - Choose industry "you perspective" whenever possible. |
| Section - Document history | a - Provide a brief table documenting the change history (optional). |
| Section - Further reading | a - Provide toward the end a list of further reading resources with liks. |
| Section - Guidepost | a - Provide a brief overview of the goal of this resource and learning objectives. |
| Section - Pre-requisites | a - Provide an unordered list of skills required for the reader to make sense of the content. |
| Section - Terminology | a - Provide a brief list terms and definitions if there are many that cannot be defined in unning text. |
| Tables | a - Avoid more than five (5) columns.
b - Precede with a brief introduction or caption. c - Avoid images within cells. d - Avoid tables nested within tables. |
| Titles | a - What is XXX? (Concepts).
b - How do I use XXX? (Tutorials). c - Best practices for XXX (Best practices). |
| Tone | a - Choose conversational without being overly familiar or folksy. |
| Unordered lists | a - Nest no deeper than three levels total.
b - Maintain parallel sentence structures. c - Terminate each list item with a period. d - Provide at least a one-sentence introduction preceding the list. Recommended. |
| Voice | a - Choose active voice whenever possible (nearly always). |