Making the Most of Your Design Analysis Documents
Sometimes it isn’t easy to get everyone onto the same page. Everyone on a development team can think we are all moving in the same (and right) direction. Still, we often have different underlying assumptions about how certain features will be implemented. When we don’t have visibility into those assumptions, headaches can ensue.
An excellent activity that helps ensure everyone has the same view when working on software development projects is the creation of what we call a Design Analysis Document. These documents give developers space to explain how they intend to implement some piece of functionality. The document can focus on an individual feature, or just on a single service or module within a system. And when the developer has to explain what they intend to do, the rest of the team can see how something might work well or could be done better.
One recent example of how a Design Analysis Document provided some great insight involved a project where we needed to implement some GDPR reporting. The reporting dealt with many components within the system, not just displaying a dialog when the user visits a web page. Part of the requirement involves deleting users’ data if they request it, while another part requires us to report to a 3rd party on the data we are using from their system. And we have to update the data in our system when it is updated in the 3rd party service. Lots of requirements and moving parts here.
The Design Analysis Document for this feature helped to ensure we all have the same requirements in mind so we can agree on a path forward. That is why, after our first review of the document, I asked the developer to rewrite the individual scenarios in a Gherkin format. This format leads to easy translation into test cases. It is also a consistent format, which makes it faster to read and, in my opinion, easier to review.
We accomplished a big win with the Design Analysis Document by quickly addressing some assumptions around implementation. The developer had made many assumptions, and it was great to see those before the developer began any coding. The first of these assumptions was the use of which services to build functionality. The developer was going to create new components when the architecture already had existing components that should host these methods. Redirecting these methods to the existing architecture components was easier during the document’s review than having to change them later. Once assumptions are committed to code, a lot more inertia is required to make any changes.
Our Design Analysis Document provided a quick way for us to review a feature and provide immediate feedback without writing any code. A huge win for the project and a lot less frustration for the developer.
If you would like to use a Design Analysis Document with your projects, here is a template to get you started.
If you have any questions, leave a comment below or reach out to me on Twitter where I’m @chadmichel.
