How do you decide appropriate documentation levels without creating unnecessary overhead?

WHAT THIS TESTS: The interviewer wants to know if you treat the Agile Manifesto as a set of trade-off values rather than a license to abandon rigor. Specifically, they are looking for judgment about information flow: when written records reduce risk versus when they become waste. Senior candidates should demonstrate that documentation is not inherently evil but must earn its keep by serving a specific audience and decision.

A GOOD ANSWER COVERS: First, audience and purpose. The level of documentation depends on who consumes it and what decision it enables. A microservice contract for 50 teams needs more permanence than a spike for two engineers. Second, living versus dead artifacts. Favor executable specifications, well-named tests, and inline architecture decision records over static wikis that drift from code within weeks. Third, lifecycle awareness. Greenfield prototypes need almost no docs beyond READMEs, while mature platforms with compliance obligations need runbooks, API contracts, and onboarding guides. Fourth, maintenance burden. Treat docs like code: versioned, reviewed, and pruned when obsolete. If the cost of keeping it current exceeds the value of the next reader, delete it.

COMMON WRONG ANSWERS: The biggest red flag is reading the Manifesto principle as working software instead of documentation. Another failure mode is prescribing a single standard for every project, such as demanding full design documents for a three-day experiment or allowing zero docs for a PCI-DSS payment service. Candidates who confuse collaboration with oral tradition also stumble: relying entirely on Slack threads and tribal knowledge ignores the 200-millisecond latency of reading versus the 2-week latency of asking.

LIKELY FOLLOW-UPS: The interviewer may ask how you handle regulatory audits without comprehensive docs, how you onboard engineers in a remote-first environment, or what you do when a critical system has no documentation and the original authors have left. They might also probe whether generated documentation from OpenAPI or Swagger counts as sufficient.

ONE CONCRETE EXAMPLE: On a platform team supporting 15 product squads, we maintained a single architecture decision record repository and auto-generated API docs from protobuf definitions. Human-written docs were limited to runbooks for incident response and a one-page onboarding guide. When a service had fewer than three dependent teams, we archived its wiki and pointed consumers to the generated schema and source code. This cut documentation maintenance time by roughly 60 percent while keeping mean time to recovery flat because runbooks remained curated.