Documentation is development, too

While organizing project documentation, I found myself applying the same principles I use in code. I settled on four main files, each with a clear responsibility.

The principles

• KISS: simple language, concise explanations. Split documents only when useful.
• YAGNI: document a real need, not a hypothetical one.
• Separation of Concerns: give each document a distinct responsibility.
• Code for the Maintainer: preserve assumptions, constraints, and reasons the next reader cannot easily reconstruct.
• Optimize for Deletion: separate temporary tasks and experiments from lasting knowledge.
• DRY: give each fact one primary home; link to it elsewhere.

Four main files

README.md — an introduction for people: what the project, component, or package is for, what value it provides to its users, and where its responsibility ends.

ARCHITECTURE.md — how it works internally: components, dependencies, execution flows, ownership, technical decisions, and constraints.

GLOSSARY.md — terms, short definitions, accepted synonyms, and names to avoid. Thanks to Matt Pocock ❤️

AGENTS.md — agent instructions and navigation: which documents to read for which tasks.

These are the main responsibilities, not a requirement to create four files in every directory or a limit on useful documentation.

Now to resist adding a fifth main file explaining the first four. 😄

A shared repository for the whole system

A shared repository, named after the organization, holds the context common to every component: the product's purpose, how its components fit together, and shared terminology. That context applies whether I am working on a server, a client, or an API specification.

Local glossaries link to the shared glossary through HTTPS URLs on GitHub, pointing to the main branch. Following those links gives the reader the current shared definitions. Each local glossary adds only repository-specific terms; local architecture describes that repository's internals and decisions.

The same scoping rule continues down the hierarchy. Documentation inside a component or package covers that component or package. Shared knowledge stays at the level that owns it.

AGENTS.md provides the navigation, including references to shared context, so the agent knows what to read for its task.

I captured this approach in a small global skill, project-docs, to use across my projects.