Having all documentation conform to the same standards makes for easier use of the documentation over time. The best time to decide on conventions is before writing is done. If you stumble on something that’s not addressed here, make sure you bring it up to the community so a decision can be made on how best to address it.
Hugo Naming Convention
- Each KB article has its own images directory within
- All file system directory names are in all lower case
- For file system directory name use key works instead of every word of the title
Titles and Headings
- The title of the page is within the title: field of the document. Don’t include the title again in the start of the document.
- Each Major, non-connective, word of the Title is Capitalized
- Each document starts with an Introduction or a Description section which explains the background behind the document.
- Headings start at the ## level.
- Use headings starting with ### to further separate smaller sections within bigger ones for ease of viewing.
- Each document contains a Summary or TL;DR section which summarizes the steps for advanced users.
- Try to use as few words as possible while remaining descriptive.
- Assume the audience doesn’t know all the background you do. Be specific and don’t omit important information.
- For actions, put key words in bold (ex: Open Chrome, select the address field at the top and fill in www.pirl.io)
- Use as many screenshots as possible to visually assist your information
- Put important information in bold
- 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 blockquotes for notes and comments
Grammar and Spelling
- Use Oxford commas
- American English spelling is used for variant words.
Table of Contents
- A TOC is recommended for documents longer than 2 computer screen lengths.
- If referencing the wiki itself, always include the link for ease of use
- Use good descriptions for you links in general
- When in doubt, link it
- At the end of each document, the names of the authors is included as well as the names of all contributors.