How do you decide the right level of project documentation?

WHAT THIS TESTS: This question tests your senior-level judgment and ability to balance short-term velocity with the long-term cost of ownership. The interviewer wants to see that you think about documentation as a tool for risk mitigation and efficiency, not as a bureaucratic checkbox. They are probing for pragmatism over dogma, and to confirm you understand that the Manifesto's use of 'over' does not mean 'instead of'.

A GOOD ANSWER COVERS: First, frame documentation as a product with a specific audience and purpose. Is it for onboarding new engineers? For the on-call person at 3 AM? For a partner team integrating with your API? The format, location, and level of detail depend entirely on this user's needs. Second, propose a tiered system based on the content's longevity. High-level architectural decisions and system boundaries warrant durable, human-written docs like Architecture Decision Records (ADRs). API contracts need precise, auto-generated specifications like OpenAPI. Business logic is best explained by clean code and targeted comments. Ephemeral implementation details likely need no docs at all. Third, discuss making documentation 'live' by co-locating it with code (e.g., READMEs, ADRs in a /docs folder) and integrating doc updates into the team's definition of 'done'. Finally, frame the decision as an ROI calculation: the cost to write and maintain the doc must be less than the future cost of not having it, such as hours spent by five engineers trying to understand a system versus two hours to write a good overview.

COMMON WRONG ANSWERS: The 'Agile Zealot' anti-pattern is claiming 'the code is the documentation' and that you write none. This is a huge red flag indicating a lack of experience with long-term system maintenance, slow onboarding, and knowledge silos. Another wrong answer is the 'Bureaucrat', who proposes a heavyweight, one-size-fits-all documentation template for every feature, ignoring the 'unnecessary overhead' part of the question. Finally, avoid vague answers like 'it depends' or 'we find the right balance' without providing a concrete framework for how you make that decision.

LIKELY FOLLOW-UPS: Expect questions like: 'How would you handle a team that consistently fails to update documentation?' or 'Give an example of a piece of documentation you wrote that had a very high ROI.' Be prepared to discuss specific practices like Architecture Decision Records (ADRs).

ONE CONCRETE EXAMPLE: For a new authentication service, we used three documentation tiers. First, an ADR explaining why we chose JWTs over session tokens, capturing trade-offs for future architects. Second, an OpenAPI spec auto-generated from code, serving as a precise contract for clients. Third, an on-call runbook in the repo's README with cURL commands to diagnose common failures. We explicitly decided not to document the internal functions, as that was ephemeral and clear from the code itself.