The file structure

Everything within the docs/ folder--and nothing else--gets published to Read The Docs, where the files are searchable and get a nice browsable table of contents sidebar. The only files in the root directory of the repo (above docs/) are configuration files and the main repo README.md, which is what you find at https://github.com/CivicActions/handbook.

Within the docs folder, the folder and file structure loosely maps to our practice areas and working groups.

Each folder should contain a README.md file with some introduction text for that section. We don't need tables of contents, because that is provided by Read The Docs.

Folders and file names should all be lowercase and avoid special characters, except for hyphens (in place of spaces).

Top level folders are given a 3 digit prefix to ensure they are sorted in a sensible way in both Read The Docs and Github. Sections should increment by 10 by default to allow for adding additional sections in between others without requiring many link updates.