Documentation

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
[Link Example](https://xoap.io)
[XOSS][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

  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