How to Write Documentation

These articles are written in Markdown and Markdown is a language that has a ton of different varieties and flavors. The two specific flavors we use are called GFM (Git Hub Flavored Markdown) and DFM (DocFx Flavored Markdown). To learn about Markdown the following resources are helpful:

• Microsoft Intro

• Cheat Sheet

• DFM Spec

If you're using VS Code there's a helpful plugin to install called DocFX published by Microsoft. It'll let you preview the HTML render of your markdown side-by-side while you write, give you syntax highlighting in your markdown files, point out errors, and give hints. Below are some examples of what you can do with DFM. They'll be most helpful to you if you're looking at them side-by-side with the DocFX preview tool.

---

Code Snippets

//This is C# code.
var x = 1;

---

Unordered list

• Item
• Other Item
• Yet another item

---

Ordered List

1. First Item
2. Second Item

---

Links

• Homepage: won't break if the file gets moved.

• Homepage: will break if the file gets moved.

• Link to the internets.

---

Images

---

Blockquotes

This little piggy is in the block quote. This little piggy is too.

This little piggy is not.

---

Notes, Warnings, and Important Cautions, Oh My!

Note

This is a note.

Warning

This is a warning.

Important

This is important.

Caution

This is a caution. Be ye warned.