On Developer Design Documentation
Often in my career I’ve had to either write or review developer design documentation, and I've seen a wide variety of them, but what is their purpose?
For decades we've had it drilled into us that we must produce developer design documents before we write any code and we are provided 10-page templates with 20 different sections that have to be filled in. Certainly, the thought goes, all those sections are either applicable or they are meant to have us think about things before we begin coding.
But we're usually being asked to create something that has never existed before and until we get to the end of the development process, how can we know everything? I suppose if you treat the 10-page template as a checklist, it works well – review everything on the list and figure out the answers while you’re designing it. But that isn’t always how those templates are used.
It’s good to understand what these design documents are for when you’re preparing them.
In some cases, you’re writing these because you need to walk others through your approach to solving the problem and having a written document is a useful way to communicate those thoughts.
In other cases, you’re writing these thoughts because you’re trying to leave instructions for the people that might have to maintain the code after you.
I’ve always suggested that the source code itself is the most important design document that will ever exist. It’s always completely accurate as to how it actually works. (whether it works as intended or not)
Yet at the same time, there are certain concepts that are not obvious from reading the source code, and you need to help someone who may not have the benefit of your … experience … shall we say, from writing the code.
With that in mind, perhaps the best answer for what to put in a design document is “the things you need to know before you read the code”. Diagrams, examples, where the source code is, how it fits into the overall system, but most importantly, explanations of the concepts that someone needs to understand before they turn to the source code, because they’re not easily grasped from the source code itself.
I recall one document produced by an Architect that was nothing but 66 pages of method names from the code, with a minimum of prose. The product used a lot of the visitor design pattern (there were, as I recall, at least 9 of them) and the design doc didn’t really cover much, if any, of the details of what was going on, just the names.
I have to ask: How is this helpful? Furthermore, how is it still relevant after the first medium size change to the code? Finally, it took a hella long time for the Architect to write all that down (I don’t think he really ever finished it) and no one could really use it, so it was a costly effort with no added value, all to check a box someone said had to be checked.
My counter example was from the same project. It was more on the lines of 10 pages, because there were three significant concepts that needed to be understood, and it documented those and gave examples of how it worked, along with pictures and diagrams to explain them to the uninitiated.
It was eventually turned into a patent application with minimal effort because it already included all the information and diagrams needed.
My advice is to rely upon the source code for the details, document the big concepts that aren’t obvious from it, use the templates to help you make sure that you've covered all the important things, and make sure you review it when you're finished with the project.