Pick the Right Section

Type: Reference·Created: ·Last reviewed: ·Team: Platform

published

Why sections matter

Every doc lives in exactly one section. You pick the section by what the reader is trying to do — getting started, learning how we work, understanding the product, and so on — not by topic. Choose by intent and there's always one obvious home.

Pick the right section

A short cascade:

1. New here, or setting up your machine? → start-here
2. About how we code, test, review, or ship — and true at any company? → engineering
3. About what a feature does (behaviour, rules)? → product
4. About how the system is built (services, data, integrations, design)? → architecture
5. About running it in production? → operations
6. A value you just look up and leave? → reference

The six sections

Section	For a doc about...	Example
start-here	Joining the team and getting your machine ready — setup steps, accounts and access, who owns what, and the terms you'll keep hearing	"Set up your dev environment"
engineering	The way we build software, written so it would make sense at any level — coding style, branching and commits, code review, testing, CI/CD, releases	"Our pull-request flow"
product	What a feature actually does, in plain terms — the behaviour, the rules, what the user sees. The what, not the how	"How Attendance models a work session"
architecture	How the system is built under the hood — services and how they fit together, data models, integrations, the security design, and the decisions (ADRs) behind them	"The service catalog"
operations	Keeping it running in production — on-call, handling incidents, step-by-step runbooks, SLOs, and recovering from outages	"Rolling back a bad deploy"
reference	A single fact or value you look up and then leave — generated tables like the API index, error codes, and config keys	"Error code catalog"

When it could fit two sections

A few topics feel like they belong in more than one place. Each has a simple rule:

• Security — writing secure code is engineering; the system's threat model is architecture.
• A module — split it by the same what / how line. Its behaviour goes in product/<module>/; all of its technical design (data model, services, integration points) goes in architecture/ — never inside the product folder. A short README on the product side links to the architecture so the two halves stay connected.
• API docs — the narrative explanation of an endpoint (how to call it, what it returns, what bites you) is technical, so it goes in architecture with that module's design; the generated index of signatures goes in reference. product only describes the behaviour and links across.

The rule behind all of them: one doc, one home, chosen by its main purpose. Every other section links to it instead of repeating it.