How we write technical documentation
We write all of our technical documentation in Markdown. See this chapter for a quick reference and guidance on how to write documentation.
Documentation in Azure DevOps
Internal Note: It is important that commits (code and documentation) are linked to the respective Work Items in Azure DevOps.
Markdown
Markdown is a simple way to format plain text that looks great on any device without using any HTML or CSS. It doesn’t permit anything fancy like changing fonts, color, or typeface – just the bare essentials that can be expressed using keyboard symbols you already know.
Standard Formatting
Italic
*Italic* _Italic_ Italic
Bold
**Bold** __Bold__ Bold
Heading 1
# Heading 1
Heading 2
## Heading 2
Strikeout
~~Strikeout~~ ~Strikeout~ ~~Strikeout~~
Blockquote
> Blockquote
Blockquote
Bulleted Lists
* Item 1
* Item 2
* Item 3
Numbered lists
1. Item 1
2. Item 2
3. Item 3
Simple Links
[Link Example](https://xoap.io)
Footnote Links
[XOAP][1]
[Microsoft][2]
Code Block
$i = 0;
$i++;
Tables
Colons can be used to align columns.
- There must be at least 3 dashes separating each header cell.
- The outer pipes (|) are optional.
- Columns do not need to be neatly formatted.
- Supports inline Markdown.
Table Examples
| Cities | Musicians | Dinosaurs |
|--------|-------|--------|
| New York | Queen | Sauropodomorpha |
| Rio | Armin van Buuren | Titanosauria |
| Tokyo | Guns n´ Roses | Pachycephalosauria |
Cities | Musicians | Dinosaurs |
---|---|---|
New York | Queen | Sauropodomorpha |
Rio | Armin van Buuren | Titanosauria |
Tokyo | Guns n´ Roses | Pachycephalosauria |
Markdown Best Practices
Using Markdown is essential for clear communication on mediums such as Git or just plain text.
Code Blocks
Use code blocks for anything more than 1 line. Use code for inline code, filenames, commands, etc.
# This is a code block
Table of Options
Use tables to communicate lists of options.
Here’s an example:
Table of Options
Name | Default | Description | Required |
---|---|---|---|
organization | Organization (e.g. RIS or XOAP ) |
Yes | |
stage | Stage (e.g. prd , dev , acc ) |
Yes | |
product | Product (e.g. infra.XO or workspaces.XO ) |
Yes | |
attributes | [] | Additional attributes (e.g. policy ) |
No |
tags | {} | Additional tags (e.g. map("Foo","XYZ") ) |
No |
:——–: should be used for “Default” and “Required” values
:——— should be used for all other columns
Use value for all values
Which will render to something like this:
Feature List Example
- Feature 1** - Explanation of benefits
- Feature 2** - Explanation of benefits
Use Block Quotes
Reference copyrighted text, quotes, and other unoriginal copy using >