I'm currently in the process of updating a design document so that it is correct and up-to-date for future developers.
Currently, the document focuses on only the facts, presenting how the design is. There is no rationale for any decisions presented. I believe that it's important to capture rationale so that developers know why something is the way it is, as that will probably affect future decisions. It's not possible for me to add rationale for all of the design decisions, especially those made before I started working on the project, but I'm doing what I can in this department.
However, some of the design decisions are, respectfully, very poor decisions given the requirements of the project. There are some good ones, though, as well.
My initial thought was that I should include a discussion of design problems and potential solutions or workarounds to these problems to focus the attention of future maintainers, but I'm not sure if the design document is a place for this type of discussion and information. I don't want a design "critique" to snowball into "ripping this design a new one" as other people work on this system and update the document, as that is clearly inappropriate.
My manager would support either decision, so it's up to me. Regardless of the approach that I take, the document produced would be officially versioned and provided to developers working on the system, typically before they are tasked with development work. It's expected that a new developer familiarize themself with the documents associated with a given software system prior to beginning development work.
Questions:
- Should a design document stick to raw facts ("this is the design") and rationale ("here is why this is the design") or should it also be used to point out non-defective issues with the design that could be problematic for future developers?
- If the design document should not be used to capture this information, what type of document should capture it, and what else should be captured with a discussion of design rationales, tradeoffs, and known issues (that aren't defects, as defects are tracked using other tools)?