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.
Best Answer
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.