Balancing Documentation and Working Software
Incorrect documentation is worse than none, so keep sources close to the code.
Provide tools for developers to make changes and arrange content to cover prerequisite concepts first. Ensure all publications can answer user questions. Organizational communication can be confusing, so starting with a specific project and holding weekly meetings to review progress is best.
Architecture Decision Records (ADRs) capture the forces and the decision that addresses them. Each ADR is numbered and has a concise title. The context section explains the forces, including technology, politics, social issues, and the project’s local environment. The Decision section outlines the response, which can be “proposed” or “accepted.” If a decision changes, it may be marked as “deprecated” or “superseded.” ADRs should be one to two pages long and describe a significant decision for a specific project that affects the rest of the project. Any team member can create an ADR using templates and is responsible for maintaining and communicating its content.
To improve the development process:
- Document before starting and repeat information for clarity.
- Structure content so readers can skip over concepts they understand.
- Use examples and tutorials to help users understand better.
