Markdown Documentation Conventions
Table of Contents
1 Background
Markdown is our primary documentation "language" for everything from
repository README.md docs, to resource docs and convention docs like this one.
2 Language Rules
All written non-coding / machine language is Canadian English.
- No oxford comma.
- Carry overs from British English like "colour".
2.1 Writing Form
Write in full sentences ending with a . or applicable punctuation.
3 Style Rules
3.1 Line Length
Max line length = 80.
3.1.1 Exceptions
Exceptions to the limit are:
- URLs, filepaths, etc.
- Long constants not containing whitespace that would be inconvenient to split.
3.1.2 Pros
Conforms with most of our code conventions.
Matches most code generation tools, fits A4 print papers and typical maximum in industry.
3.1.3 Cons
None, mostly subjective.
3.2 Indents
Indent is 4 spaces.
3.3 Headers
3.3.1 Numbering Format
Headers are numbered the following format.
---
# N Header 1 (Title) Example Name Here
## N.N Header 2 Example Name Here
### N.N.N Header 3 Example Name Here
#### N.N.N.N Header 4 Example Name Here
---
- N is a number.
3.3.2 Writing Format
Headers are named with standard Title Formatting.
3.3.3 Horizontal Lines
Use horizontal line breaks --- to separate long sections of writing.
The general recommendation is to separate on Header level 1 & 2 to improve
readability.
3.3.4 Section Links / Header References
Use header references when possible to make referencing easy.
3.4 Standard Markdown Syntax
- Point form.
**Bold.**
_Italics_
**_Bold and Italics_**
---
3.4.1 Advanced Formatting Syntax
For advanced syntax use as appropriate.
See full documentation on GitHub Docs: Working with advanced formatting
3.5 Code Blocks
If code blocks are used do your best to declare the language for clean formatting and clarity of the intended language.
Follow the applicable code conventions for the code within the code block.
3.6 Relative Links
Unless specified, the relative link must always start at the root directory of the repository.
See full documentation on GitHub Docs: Relative links
3.7 Math Expressions
3.7.1 Inline
Use the inline format as shown below.
Inline: $x = \frac{-b \pm \sqrt{b^{2} - 4ac}}{2a}$.
Inline: $x = \frac{-b \pm \sqrt{b^{2} - 4ac}}{2a}$.
3.7.2 Blocks
Use the block format as shown below.
Block:
$$f' \left( x \right) = \lim_{ h \rightarrow 0 } \frac{f \left( x+h \right) - f \left( x \right) }{h}$$
$$f' \left( x \right) = \lim_{ h \rightarrow 0 } \frac{f \left( x+h \right) - f
\left( x \right) }{h}$$
4 Other Media
Links, pictures, etc are very helpful use them appropriately to write good documentation.
4.1 Pictures
Include a pictures directory at the highest root directory of the picture
reference.
4.2 Unicode Emojis
- Unicode's emojis are allowed, but be sensible in usage.
5 Common Content
5.1 Table of Contents
Include a listed version of a table of contents for long documentations following the format below.
# Title Here
---
<details markdown="1">
<summary>Table of Contents</summary>
- [N Header 1 Example Name Here](#n-header-1-example-name-here)
- [N.N Header 2 Example Name Here](#nn-header-2-example-name-here)
- [N.N.N Header 3 Example Name Here](#nnn-header-3-example-name-here)
- [N.N.N.N Header 4 Example Name Here](#nnnn-header-4-example-name-here)
</details>
---
...