13

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)?
|improve this question
  • 1
    The design documents are not the appropriate place for such criticisms, but it is important that those concerns be aired through some appropriate means. – Robert Harvey♦ Sep 8 '11 at 15:04
  • 1
    @Robert That seems very much like an answer to me, although perhaps expanding on what you would consider appropriate means. – Thomas Owens♦ Sep 8 '11 at 15:20
  • Errata, perhaps, or Requests for Comment. Design documents should go through a (more or less) formal revision process. Allowing people to mark such a document with criticisms seems counter to that process, unless you use something like "margin comments" in a Word document (they can be turned off, showing the "official" document). – Robert Harvey♦ Sep 8 '11 at 16:20
7

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.

|improve this answer
  • I like that format quite well. I might have to borrow/steal it to try it, if you don't mind. Perhaps I'll even corporate-templatize it and pass it around my team, if it works well for me and there's no objections from you. – Thomas Owens♦ Sep 8 '11 at 15:19
  • 2
    @Thomas Owens: Go for it! It works well here, and I also like it. :) I don't think you can "steal" it since I know people in other companies do similar things, it's hardly "new" ;) – FrustratedWithFormsDesigner Sep 8 '11 at 15:26
5

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.

|improve this answer
  • Your last two sentences are especially true. Everything that I planned to discuss was either problems that I faced implementing a feature/fixing a defect, writing tests, or discovered during profiling and not just an overall critique of the design as a whole. Do you recommend documenting this in the design document or a separate document? – Thomas Owens♦ Sep 8 '11 at 15:09
  • "problems that I faced"? Essentially irrelevant. The code is the solution, the problem is usually just a comment. "discovered during profiling" means it's fixed, so it's in the past, and has no relevance at all. Don't use this as a "journaling" exercise. – S.Lott Sep 8 '11 at 15:25
  • Some problems that I faced would have an impact on future enhancements/defects in the same module, such as a previously undocumented dependency that, by itself isn't a defect (so it can't be filed as one), but changes how you need to approach problems in certain modules. This is so tightly coupled to the system that it can't be changed at this point with a reasonable amount of effort. This needs to be captured somewhere for reference. Also, profiling was a fact-finding effort, nothing was fixed - they still exist and still meet current requirements, but are potentially future issues. – Thomas Owens♦ Sep 8 '11 at 15:30
  • Just to clarify more. An example is that I had a defect A that I fixed. However, when fixing A, I encountered several issues that were undocumented. This is now documented in the code, but needs to be captured somewhere else as well. It's typically below the class level and within methods, so these relationships and potential problems wouldn't be captured on a class diagram or sequence diagram. They can't be fixed or addressed with a reasonable amount of effort, and they don't cause functional or performance problems. How should I best capture this information outside of the code? – Thomas Owens♦ Sep 8 '11 at 15:38
  • 1
    @Thomas Owens: Consider that you are unique and everyone else is lazy. "I can't imagine anyone who doesn't". You need to meet more people and see how little stock is put in documentation. For example. 100's of StackOverflow questions -- every day -- are trivially answered by tutorials. Yet. Folks don't read and ask perfectly silly questions. I can only repeat what I've observed for the last 3 decades. Folks don't read. Your experience may be different. You asked for advice. I gave it to you. – S.Lott Sep 8 '11 at 20:50
2

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.

|improve this answer
1

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.

|improve this answer
0

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.

|improve this answer
  • They aren't necessarily things that can be fixed, but most are "gotchas" that many people might overlook or areas that aren't entirely obvious how they are related. A time-sensitive approach is a good idea, though. This application is about 5 years old, and they simply had access to different tools and technologies back then, and that needs to be kept in mind, regardless of the approach I take, – Thomas Owens♦ Sep 8 '11 at 15:24
0

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.

|improve this answer
  • All documentation and knowledge is kept in Word documents, Excel spreadsheets, Visio or Rational diagrams, and PowerPoint presentations that are versioned. I would either need to add to the design document or create a new document with a tool and version that in the document repository for the project. – Thomas Owens♦ Sep 8 '11 at 15:33
  • @Thomas Owens - I see your predicament then. I still wouldn't put it in the main document, but that sort of discussion is good and shouldn't just live in the memories of the original devs. Maybe add it as comments on the main document itself? That way you can give insight without it being apart of the main text. – Tyanna Sep 8 '11 at 16:05
0

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.

|improve this answer
  • Definitely that last sentence. I don't know why Jim, Bob, and Steve decided to design their app in this way, so I'm not even going to try to rationalize it. I can, though, make sure that a particular module or component is associated with requirement(s) and also rationalize decisions that I made. – Thomas Owens♦ Sep 9 '11 at 10:21

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.