Andreas

Reviewing technical design documents

Software Engineering /

It is normally good practice to let technical design documents review by other people, most likely by another developer. The way this is usually done is to pass the document to those other people, and they read through it line by line, trying to understand it and looking for inconsistencies.

But does this really help to verify the usefulness and completeness of the information provided in the design document? Does it help to ensure that all necessary information is available in the document? I do not think so. There might quite some typos being found, and probably also some sections which are not well written and hard to understand, so these can be enhanced. But I think that simply reading the document does not provide much benefit in ensuring that all important information is contained in the document.

Instead, why not try another approach (the assumption is that the source code already exists for the system which is described in the design specification, and that the review step is a late step in the development process to make sure that the specification contains all necessary information):

  • Introduce a subtle bug into the source code
  • Give the source code together with the design specification to another developer
  • Have the developer solve the bug only with the help of the specification and the source code itself

I am pretty sure that this approach will uncover many gaps in the design document. The developer who needs to solve the bug will come back with all the questions, if the answer is missing from the design document (How do I build the software? How do I launch the software? How do I debug the software? How is the tier architecture of the software? Which database do I need? Why did you use the visitor pattern in this case? Why is class XYZ a singleton? And many more). Each of these questions point to information which is missing in the design document and which needs to be included.

The benefits of this approach are:

  • For sure, it is fun for the original developer to introduce some subtle bug into the code base. When else are you entitled by your management to explicitly add bugs to the code base? Of course, make sure to do this excercise in a sandbox or at least on a separate branch which is ensured to never be merged back into the production branch.
  • Through the hands-on excercise, the developer who does the review gets a much deeper insight into the functioning of the system. You get an implicit transfer of information about the software module.
  • The quality of the design document will increase a lot and the document is much more worth reading in the future, when even other developers need to fix bugs in the module or enhance it.

Of course, if the system is already in production and bugs have already been reported by the customer, you do not need to introduce bugs yourself – but even in this case, when doing some particular bug fixing, take the chance to review any existing technical design document and enhance it with any missing information. It will help in the future.