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.
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.
Write your specs in Markdown. AsciiDoc is also OK if you need it.