Docs Style Guide
Style Guide Rule #1: Follow the Style Guide. Rule #2: See previous rule.
TL;DR? We don't do that here!
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.
General Guidelines
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
Titles, Headings & Summaries
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.
Links
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 updated
Was this helpful?