Should a design document contain a discussion of the pros/cons to a given design or should it focus on facts and rationale?

Question

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)?

Answer 1

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.

Answer 2

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?

It's not "either-or".

No one reads documentation in the first place. They skim -- at best. Therefore, write as few documents as possible. One document is all anyone has patience for. A second "non-desgin" document with "other issues" is unlikely to get read at all.

Advantages of one document? People might read it.

Disadvantages of one document? Few. Mostly it gets out of date.

Advantages of multiple documents? None.

Disadvantages of multiple documents? Please read up on the DRY principle and literate programming. Multiple documents means multiple sources of errors. Each document disagrees with the other and disagrees with the code. This is pretty obvious. This is the path of madness.

---

Avoid hand-wringing.

A pros-and-cons document can drag on into indefinite depths of what-if and attractive nuisance discussions.

If you feel that it's necessary to present pros and cons, keep it short and to the point.

Focus on what is.

Keep what is not down to the bare bones.

If you have done benchmarks, studies, or actually explored alternatives, document that. But if you're just considering alternatives, minimize it.

This should not be your personal history of trial and tribulation.

• Had a problem? Fixed it? Took weeks? Really struggled? Barely an interesting anecdote. It's fixed in the code. The previous versions, wrong versions, buggy versions and low-performance versions don't matter. They're blog-fodder at best.

• Still have a problem? Not fixed? That means there are alternatives. Document this.

Answer 3

There are 3 important facts in the process of decision making:

• What was tried and did not work (and why it didn't work, because you're targetting a moving target)
• What is
• What could be (just waiting for X to be implemented...)

However, apart from "What is", all the others will confuse the reader and prevent her from groking the system.

I like the idea of capturing the other 2, though they are less interesting for learning the system, they can be time savers when changing it.

Therefore, I would build on the idea exposed @FrustratedWithFormsDesigner, with a twist. Instead of creating yet another document, with a life-cycle of its own, I would tack-on an annex section. Then for each decision worthy of discussion, I would point to the relevant entry in the annex.

Answer 4

Yes. A design document should explain the benefits, risks, and assumptions associated with the design being described. A design document has several purposes:

1. Get the design written down so that everybody understands it, and so that each person's understanding doesn't drift over time.

2. Communicate the design to non-technical people working on the project.

3. Assist in scheduling, resource allocation, cost estimation, and other kinds of planning.

4. Becomes an important part of the overall project documentation. When you join a project in progress, or have to maintain one that's been completed, life is a lot easier if there's a well-written design document.

5. Is often one of the deliverables required by contract.

(There are probably others, but these are a good start.)

Every one of these purposes is well served by a design doc that clearly explains why this design was chosen and what the associated risks are:

1. It's essential that everyone on the team know what the risks and benefits are so that they can work together to avoid those risks and make best use of the design's benefits.

2. For non-technical team members, understanding the risks and benefits is often more important than the particulars of the design itself.

3. Risk management is one of the most important things a project manager can do to ensure success, and the first step is to identify the risks that need to be managed. It should be up to a manager to decide how to deal with risks, but it's the responsibility of the designer to point out known risks of the design.

4. Even when a risk is no longer a problem, it's often useful to have it documented because it can help explain the situation at the time the design was created. That can let a maintainer decide something like: "Okay, they did it this way back then because... but that's no longer a problem, so I can replace that code with a simpler, faster implementation." Same goes for benefits, of course.

5. If you're working on a project for a client, then it's particularly important to document risks and benefits. That puts the client on notice that things could go wrong under certain circumstances, or that requesting changes to the design could jeopardize some of the promised benefits.

I gather from the question that you're working with an existing design document for a system that has already been implemented. In that case, many of the possible risks are no longer risks, so it doesn't make much sense to try to document them after the fact. However, you now have the advantage of hindsight as you can see the parts of the original design that didn't work out so well. I think you should either: add a separate section that identifies current problem areas and proposes solutions (including associated risks!); or create a separate document that does the same thing. This new section/document may evolve into the design document for the next version of the software.

Here's a blog entry on writing design documents that you may find helpful.

Answer 5

If there were valid reasons for avoiding more obvious or standard solutions, those should be noted. You'll save someone a lot of trouble. However, a particular technology may improve over time, so your reasons may not be applicable. A future developer can then use their own judgement.

I don't know if there is much benefit to pointing out all the short-comings. It may not be practical to make the changes or other priorities will take place. You may fix some of them in the near future and this will just be one more thing to update.

Answer 6

I personally wouldn't put it in the design document. A design document should outline how it is, not why it is.

If you feel there is a good need for a back story as to why the design is the way it is, perhaps you should put that in a wiki article (or whatever knowledge base your company uses) so that there can be a history of the evolution of the design. People can go and read it, edit it, and add suggestions. That way it's more of a open discussion instead of a brow beating in a document.

Answer 7

I agree with you about putting rationale in the design document.

Anyway,

in the process of updating a design document written by someone else, I would stay humble and not try to guess why such decision has been taken.

So,

I would insert rationale only about changes that are made in the design during maintenance.