documentation

Document code rationale by co-locating concise explanations of design decisions directly with the related code. This practice applies to inline comments, docstrings, ADRs, and READMEs to ensure long-term maintainability.

Write a concise ADR that captures why specific decisions were made and what constraints shaped the design. Attach a short README update to explain the rationale and maintain alignment with the evolving codebase.

Documentation goes out of date when it lacks lightweight governance and co-location with code. Prevent drift by applying consistent terminology, concise language, and simple guidelines to keep docs updated as code evolves.

A README should include concise explanations of code rationale and align domain terminology across code and documentation. This ensures shared understanding and reduces confusion across software projects.

Use ADRs to capture broader architecture decisions and constraints, while inline code comments explain specific local logic. Both require concise language and co-location with related code to improve project maintainability.