Use Markdown for documentation

The most universal documentation “format” is a bunch of Markdown files inside a project’s doc/ directory. Here are some projects that follow that convention:

• io.js (and Node.js)
• stylus
• puppet
• salt (uses .rst)
• pip (uses .rst)
• npm
• composer

In my opinion, “a bunch of Markdown files” is good because:

• It’s easily viewable in GitHub
• It can be made into a Jekyll (GitHub pages) site easily
• It can be made into a Sphinx site easily
• It’s a common documentation format that you can get some tools to generate to