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 |

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

:——–: 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

1. Feature 1** - Explanation of benefits
2. Feature 2** - Explanation of benefits

Use Block Quotes

Reference copyrighted text, quotes, and other unoriginal copy using >

References