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!
