At our company, we do not use any product design documents. We have three employees total so all product design discussion happens in person, or on Slack. (We are also on the basic Slack package that only allows viewing the most recent messages.)

Our product is still in early stages, and we often revisit design elements that were decided on months ago.

A problem that we face on a distressingly frequent basis is forgetting why a product design decision was made. This results in hours wasted retreading the same ground.

How can we effectively record the rationales behind design decisions?

Our workflow is based on Pivotal Tracker. One solution that occurs to me is to record the rationales for all relevant design decisions as comments on the user story itself, but this seems unreliable.

To be 100% clear: I am not talking about the design of code. I am talking about the design of the product that is realised by the code. In other words, I am not talking about decisions like "should we structure this class using composition rather than multiple inheritance?"; I am talking about decisions like "should we require a user to confirm their email address before being able to log in?".

The purpose of the documentation is to allow the business to view a record of why decisions were made, to aid in making further decisions about the same topics.

  • 13
    If you feel you need a form of design document then why not just create a design document?
    – MetaFight
    Commented Feb 21, 2016 at 16:41
  • I suppose the rationales will be recorded as prose, written prose at first guess. Who is the intended reader for those? Commented Feb 22, 2016 at 7:38
  • Why do you say that recording this on the user stories on Pivotal seems unreliable? I've never used that software, but ordinarily a ticket is a good place to record the motivation for raising the ticket. Don't just enter "Require user to confirm email address", enter "Require user to confirm email address. This helps because..." Are you saying it's unreliable because you might not bother doing it (i.e. you want a process that forces you to do the right thing), or unreliable because old Pivotal stories disappear into a black hole and you won't find them, or is there some other problem? Commented Feb 22, 2016 at 12:22
  • Who are the authors and who are the consumers of this documentation? It sounds to me like "the business" is the author and everyone are readers of it? Would that be correct? (I get that you are small right now, but if you were to grow what would the answers be?)
    – mlk
    Commented Feb 22, 2016 at 12:49
  • I would suggest "should we require a user to confirm their email address before being able to log in?" kind of decisions should go under acceptance criteria.
    – kumards
    Commented Feb 22, 2016 at 14:40

5 Answers 5


You record rationales behind design decisions by writing them down. Ideally nearby the item which is subject to the decision (which is not a "user story" - user stories are descriptions what has to be implemented, not how).

That is especially what comments are made for - to record why a specific piece of code or structure looks like it does (and I am not talking exclusively of code comments). If the subject of your design is a function, make a introductory comment to the function. If it is a class, make a comment at the beginning of a class about the rationale. If you have a bunch of classes which should all follow the same structure, add a separate design document (like a "readme" file) to the package containing those classes. If the subject of your design is a UML diagram, add comments to the description section of the diagram.

IMHO design documents may have their value, but if they describe things too "far away" from the item which they describe, they tend to become inconsistent very quickly. So my recommendation is to put any design documentation as near to the designed item as possible.

Use separate documents only when you want to document design decisions which affect many different places of your code in a cross-cutting manner. When you use them, try to make them part of your code base and place them at the corresponding hierarchy level of the designed subject (so if you make a design decision for one module which consists of many source code file, place the design description "inside" that module, but not in one class file, not on a "top level description" which is valid for other modules, and definitely not in a separate Wiki outside your SCCS. If you want to record some "high level", product wide design decisions, then a top level document maybe the best place, but make sure the this document stays on that level of abstraction.

  • Regarding comments: wouldn't you say that the purpose of comments is to describe code? Because the kind of problem I am talking about is design issues, like: should the user have X permissions given Y account settings? The purpose of code is to enable the design, so I don't think the appropriate place to discuss the design is in the code.
    – henrebotha
    Commented Feb 21, 2016 at 16:48
  • 5
    @henrebotha: You seem to have a different idea than me about what design is, can be, or should be. Code is design. Structure of code is design. Structure of user interfaces is design. Meta structures of code or classes is design. A question like "should the user have X permissions given Y account settings" sounds to me like something you do not want to hardwire anywhere into your software - sounds more like a configurable requirement. How you implement that requirement in code maybe a design decision, so you can comment it somewhere in your code.
    – Doc Brown
    Commented Feb 21, 2016 at 16:55
  • 2
    @henrebotha: if you hardwire permissions X to account settings Y, there will code be affected from that decision. Some code which controls the permissions, some code which manages account settings, some UI code, some controller code. So there should be a comment in the code at all those places. Of course, to avoid repetitions, all comments may refer to a separate design document, if there is one rationale behind it which affects many different places (as I told in my answer)..
    – Doc Brown
    Commented Feb 21, 2016 at 17:03
  • 1
    I'm not disputing that design decisions affect code. Of course design decisions affect code. That still does not mean that comments are the right place to record product design decisions.
    – henrebotha
    Commented Feb 21, 2016 at 17:15
  • 1
    @henrebotha: it depends what you mean by "Product design decisions". "Product wide" design decisions may belong in a document at the "top level" of your product documentation. If you mean any kind of "design decisions inside your product", some of them belong into code comments, others not. But I am not just talking of code comments, see my edit. I am talking of any form of comments (inside code or in separate documents) you make part of your codebase.
    – Doc Brown
    Commented Feb 21, 2016 at 17:19

Consider an agile approach. I mean, if you have the time resources and excellent writing skills to write down every design decision you guys make along with their rationales, just document everything. Realistically speaking, I'm assuming you aren't in such a position. An agile approach can help with a key challenge for documentation of rationales: you often don't know which rationales were the important ones until later.

Let's approach the problem from a holistic point of view. You guys have rationales for your decision. They're trapped in squishyware right now, the brains of the team. Despite the amount of credit documentation gets, storing rationales in sqishyware isn't all that bad. We're actually really good as a species at remembering the important things. Its why every major corporation has "tribal knowledge," even when those corporations seek to document away all that tribal knowledge.

Now you have a problem. You are finding that the sqiushyware isn't holding onto the rationales good enough. Good for you for realizing there is a problem, and identifying that it needs to be solved! That's not always an easy step! So we're pretty sure the solution is to offload some of that rationale into documentation. However, that's not enough. We can never forget the second half of the puzzle, which is re-loading the rationale into the squishyware when you need to make a decision. I've seen plenty of teams which document everything like crazy, but the content isn't actually organized to help make good decisions, so they end up forgetting rationales even though they're written down.

So you have a two step process. You need to get the rationale out of the squishyware and into documentation. Then you need to make sure that documentation is organized well enough to bring the rational back into squishyware when you need it! Now I think we have enough of a problem statement to realize where the challenges will like. When you are documenting, you typically don't know who is going to be looking at it later, or what they're looking for. Likewise, when you are looking back at documentation, you typically don't know what you're looking for (at best you may know when).

So a big company may try to handle this in two big blocks. First they may go develop requirements based on what people need when they're researching the documentation. Then they use those requirements to build a process for developing said documentation. And, if I dare say so, then everybody complains because almost nobody knows exactly what documentation should look like on day one. The documentation is always incomplete, and the developers are always complaining that the process is too burdensome.

Time to go agile.

My advice would be to start up an agile effort to improve your documentation process: the whole nine yards from squishyware to document and back to squishyware. Recognize up front that you will lose some information because your process isn't perfect, but that's okay because you're still trying to figure out the process! You'd miss more if you tried to create a one size fits all solution.

A few particular tidbits I'd look at: * Explore informal documentation. Formal documentation is great, but its time consuming. One of the purposes of documentation is to release information from developer squishyware and put it on paper. Informal documentation keeps the cost of doing so to a minimum.

  • Accept unreliable documentation formats. Nothing will be right the first time. It's better to get the data and figure out how to make it reliable later. For example, you might document your rationales in a <rationale></rationale> block or something similar, which would make it easy to harvest that data later. Storing the rationales in a user story, for now, is just fine!
  • Never forget the value of organization. Find out how you, as a team, like to search for rationales in the documentation, and try to document to that. Each team will have a different process. On one of my teams, we could never find the ticket that had the rationale on it right away. What we could do is find a line of code which mattered, do a svn blame to find out when it changed and why, then go look at the tickets. Once we were there, we typically put all of the rationale we needed right on the ticket. That just worked for us, find out what works for you.
  • Organic documentation can grow over time. It is rare for developers to know which rationales are most important the day they needed to write it. We usually find out which ones were important later. If you have a grooming process for the documentation which permits the developers to manage their own little garden of rationales, the important ones will rise to the surface. Even more important, rationales may change. You may realize that two different changes, with two different rationales, were really best described by a single rationale that works for both. Now there's less content between you and decisions!

I'd suggest setting up a private instance of MediaWiki or some similar wiki software. It's really easy to organize and re-organize content there, and you could copy and paste new discussions directly into the discussion tab of the relevant wiki article(s). We used MediaWiki at my last job for all of our architecture and API docs, and it was a lifesaver.

  • 2
    Architecture & high level decisions - might be ok. API docs - NO! Some people in our organization tried this in the past an it is always the same - low level docs get out-of-sync with the code. Wikis don't interact well with the VCS, people forget or don't take the time for updating it etc. API docs belong in the code, in front of the functions they describe. If you feel you need them in your intranet, use a HTML generator like doxygen to extract them from there. But do yourself a favor and don't maintain them separately, manually, in a Wiki.
    – Doc Brown
    Commented Feb 22, 2016 at 6:39
  • 3
    I firmly believe that all design rationales should be written down within the source code repository. Any other place, and they not only get out of sync, they also won't remember their history. Commented Feb 22, 2016 at 7:02
  • Downvoting a solution that works... Wow. OK then. Commented Feb 22, 2016 at 12:15

Think about it from the point of view of the coder that is going to be asked to change it in 12 months time.

If you add this business rule as an automated test then the change will be made AND THEN you will get from the failing test the contradictory requirement (and hopefully you capture the person associated with the original requirement and their reason for specifying it).

I regard the design doc (the place where you put your BPMN diagrams, Transaction diagrams, even a photo of the whiteboard etc.) as being similar to the code, just a non-executable form... which means what you are trying to record is akin to a code comment, but a (testable) requirement specified up-front in the design. Presumably if you are an agile shop you still design your code, you just do it at the last minute before writing it. Keep this in the code-base with all the other project documents.

Whatever you do, make sure it is stored in a way that is searchable (for example you may want to pull up all business rules related to "authentication" when specifying new changes).


As always when you write something, you have to ask yourself who the intended audience is. I strongly believe that design documents are there for my peer developers, current or future ones. The document helps them understand what I'm building or what was built (high level overview) and more importantly why. It is a place to document alternatives you considered, the pros and cons of each.

Saying that it's okay for some design to live in people's brains leaves out that developers move on and find different jobs, taking with them that valuable information.

Having your code be the only design documentation is like finding your way around town using a magnifying glass. A map is so much more useful (unfortunately there's no GPS equivalent for source code).

I do agree that design documentation rots even faster than code does. And since there is no validation possible between the two, the only thing you can do is to keep them close together. IMO, a dated design document still provides valuable information.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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