Docs Style Guide
Style Guide Rule #1: Follow the Style Guide. Rule #2: See previous rule.
There is no summarizing this page. The Style Guide must be read in full and followed. Deviating from the Style Guide should be done after discussion, allowing the Style Guide to change as needed for practical purposes.
When using a Style Guide, the documentation portal will have a single voice for the reader. Without a style guide, our readers will have to adjust their expectations for each document, making it a less than ideal experience with possible, unnecessary errors and omissions.
- Try to use as few words as possible while remaining sufficiently descriptive in your instructions
- Be specific and don’t omit important information or consideration that will benefit the informed decision of the reader
- For user action instructions, put key words in bold (example: Open Chrome, select the address field at the top and fill in ethoprotocol.com)
- Use italic text for names and short references/quotes
- Use as many screenshots as possible to visually assist your information and dovetail with the action instruction information in bold (see above guideline)
- Use triple code tags to distinguish terminal commands, text editor contents and code blocks
- Use single code tags to distinguish anything you find needs to stand out
- Use block-quotes for notes, comments and lengthy quotes/references
- Each non-connective (unless used as 1st word in title) word of the Title is Capitalized (example: This is a Sample Title)
- Each document starts with a Summary, Introduction or a Description section which explains the background behind the document and/or any major takeaways. Most people will only use this section, we need to make it good.
- Headings start at the #/1st level.
- Break up your content into logical 2nd/3rd level headings to help the reader navigate the content and find useful information.
- When referencing this documentation portal, always include the link for ease of use
- Use good descriptions for your links in general
- When in doubt, link it for the reader's benefit
Last modified 2yr ago