Documentation Guidelines
Contents:
Overview
Proper documentation is very important for any business. In this guide, we will detail how to create documentation that is consistent and efficient. Refer to the resources document for additional information on sections below.
Markdown
Markdown is a way of writing rich-text (formatted text) content using plain text formatting syntax. Markdown is a simple markup language that is typically used to write documentation. This page is written in Markdown and then rendered as HTML for consistent formatted viewing. Refer to the Markdown section in the resources document for more information about Markdown and its syntax.
Terminal Commands
When you are describing terminal commands, write a code block. Inline code blocks are denoted with a single ` surrounding the code. For example, this is what it looks like in standard text:
`$ echo Hello World! `
This is what it looks like in a completed Markdown document:
$ echo Hello World!
When you want to write multi-line code blocks, use the following convention. Start with 3 ` and then the name of the language you are using. Then on a new line, write your code. Finally on a new line, complete the block with 3 `. For example, this is what it looks like in standard text:
```bash
$ echo 'Hello World'
Hello World
```
This is what it looks like in a completed Markdown document:
Writing terminal commands in code blocks is cleaner than regular text or screenshot images. These code blocks are easily copyable, allowing for easier use elsewhere.
In instances where you would like to demonstrate a command and its corresponding output, it is best practice (and general convention) to use a dollar sign ($) in front of the command.
Lines that start with the $ are known to be inputted terminal commands, and lines without it are known to be output. For example:
Inline Documentation
Use inline documentation (code comments) when writing code. Inline documentation is helpful when other developers are reading your code so they dont have to spend time reading the entire code to understand a few lines.
Inline documentation should:
- Explain why you do something (if it's not immediately obvious)
- Reason about the code
- Mark up code for refactoring
Refer to the inline documentation guide in the resources document for best practices on inline comments.
Fenced Code Blocks
Python Markdown does not allow nested fences under blockquotes, lists, or other block elements. The SuperFences extension allows for arbitrary nesting of code and content blocks inside each other. This is enabled via mkdocs.yml.
Refer to the resources document to learn more information about the SuperFences Extension and fenced code blocks.
MkDocs
The docs are hosted using Mkdocs. MkDocs is a static site generator that allows us to view our final documentation output. The documentation source files are written in Markdown and configured with a single yml config file.
We also use the theme Material for MkDocs. Refer to the resources document for information on Material for MkDocs.