DesignLog

If I see design documentation at all, this often only shows what people decided to do, rather than also recording why and how they arrived at this decision.

I started my career at Philips Electronics in 1976, at the same time Philips started to sell its first microprocessor: I taught people how to start using it, with related interface devices. We got a notebook (no, not a computer! just paper) to note our thoughts, experiments, and findings chronologically. It was difficult, however, to retrieve an idea I had several weeks before, because it was buried in many pages of hardly readable handwriting.

Nowadays we can use a word processor, add pictures, organize by subject rather than chronologically, and search through the text. We log our thoughts in chapters, which start with what we have to achieve (requirement), end with our decision of how to achieve it (implementation specification), with in between how we arrived at this decision: the reasoning, assumptions, calculations, questions and answers, possible solutions, decision criteria, and the selected solution (design).

A bit simplified: If we take the tops of all the chapters, we should have all the requirements (until now), and if we collect the bottoms of all the chapters, we should have the implementation specification for these requirements.
The DesignLog should of course be properly reviewed to find possible issues before they pollute the implementation.

Because the choices and design are now well documented, in the maintenance phase (often the largest portion of the cost of deployment of software!) minimum time is lost. When people ask “How detailed should it be?” my reply is always: "If someone has to change something in the software one year later, they should be up and running within one, or at most two days."

When QA asks development to review the DesignLog, if there is one: they can (help to) review, and use this information to define and optimize their test-cases. If there is none: this is a good time to introduce the DesignLog concept.

In order to keep the code (or more in general: the implementation) consistent with the design, every time we see a reason to change the code/implementation, we should always keep the discipline to first change the design and only then make the code/implementation according to the updated design. Because discipline is difficult, QA can help by always first reviewing the design, and then checking that the code/implementation does exactly what the design says.
If I suggest to review software, the developers usually just show me the code. If I ask "Where is the design?", I often see a surprised face (I hope you are different). Again: that's a good moment to help them with learning how to design properly. With a proper and properly reviewed design, defects are hardly introduced. Without the design, we will spend a lot of time testing and debugging. That's an absolutely unnecessary waste.

Quality costs less!