Structural and Naming Conventions

Top Level Organization

The assets in this project are organized as follows.

• docker-compose.yml -- Docker Compose configuration used to run the documentation site locally
• mkdocs.yml -- configuration for MkDocs
• docs -- document content
  • front-matter/ -- all of the stuff that precedes the actual articles (e.g. preface, introduction, terminology, etc.)
  • articles/ -- articles organized by groups
    • group-designators.txt -- documents the assigned article groups
    • [A-Z]/ -- articles in a given group <NNN>-<short-name>.md -- a specific article
  • rear-matter/ -- all of the stuff that follows the actual articles (e.g. references, contribution guide, etc)

Structuring and Naming of Articles

1. Articles are organized in named groups.
2. Each group is assigned a single letter of the alphabet. The assigned letters are documented in group-designators.txt
3. Each article is numbered within its group.
4. Each article has a global identifier formed by joining the group letter with the article number; e.g. S3.
5. Articles are organized under /docs/articles in this repository. This directory contains subdirectories that correspond to the designated group letters.
6. Each article is stored in its own file. Article files are named using the convention <NNN>-<short-name>.md where NNN is the zero-prefixed article number and short-name is an abbreviation of the article title; e.g. 002-tagging-resources.md