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)?
Best Answer
If the pros and cons can be summarized in a sentence or two, then it's OK to put them in a design document. Anything longer should be separated out.
Where I currently work, there is usually a separate "Design decicions" document to track all Big and Important decisions. Often formatted with a paragraph describing the problem (such as "Some files need to get moved from a server to certain users at the end of each processing cycle, there are many ways to do this..."), a table with columns "solution description" (such as "move files via FTP"), "pros" (such as "Easy for users to manage"), "cons" (such as "not secure enough for ABC-XYZ compliance") and a conclusion that explains why a particular decision was chosen (such as "FTP will not be used because it will not be able to meet certain compliance requirements"). The design document usually only references the chosen decision, and may recommend readers to read the decicion document for a full description of other options.