helidon/docs-internal/README.md

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.