
# Internal Documents and Specifications

This directory contains internal documents and specifications. These 
fall into a number of categories:

* Guidelines and best practices
* Design documents
* Feature proposals
* Or pretty much anything else

By keeping our documents as source code we can easily find them and easily review them.

# Specs vs GitHub Issues

In many cases GitHub issues are sufficient for tracking requirements and basic
proposals. But a spec might be more appropriate if you want an easy to review,
living document with a fair amount of detail.

# Use Markdown

Write your specs in Markdown. AsciiDoc is also OK if you need it.

