Topics / Engineering practice
A software design document should explain the decisions the code cannot.
Document responsibilities, interfaces, important trade-offs and how the design satisfies requirements. Keep the links current as the implementation changes.
Write for the engineer making the next change.
A class inventory can be generated from code. The more valuable content explains why responsibilities are separated, which failure modes shaped the design and what an alternative would break. Link those decisions to the requirements they serve.
Illustrative example
Why is the retry token stored before dispatch?
The ordering protects a promise about duplicate effects after a crash. A diagram of the components alone does not explain it. Record the crash window, the selected ordering, the recovery behavior and the verification that exercises it.
Keep a small, navigable structure.
- Component responsibilities and their owning requirements.
- Interfaces, input assumptions and failure responses.
- State and persistence rules, including recovery.
- Consequential decisions and rejected alternatives.
- Implementation and verification references.
- Open questions and the revision the description covers.
Separate intended architecture from the current implementation where they differ. A diagram that silently follows accidental code structure can erase the reason for a needed repair.
Generate the repeated parts, review the argument.
Proof can generate documents from requirement data. Inspect available templates and preview their output before choosing an artifact for a review.
proof doc list-templates
proof doc preview sdd --format mdGeneration reduces copying. It does not invent missing design rationale or establish that the document is complete for your project. Review the output against the actual decisions the reader needs to make.
Try it on your software
Bring a design that takes too long to explain.
We can connect its consequential decisions to requirements, implementation and checks.