When the development is based on agile methodology such as SCRUM and especially, distributed SCRUM, at some point, the need for design document becomes key to success of sprint delivery with as lesser technical debt as possible. In that regard, there has been questions around whether to have something such as design document at all. Many of those practicing agile as a developer just hate the idea of writing design documents and relate it with waterfall development model. They give the argument that a) in agile development, design have to change as we develop and b) thus, the design document may go obsolete in no time. To a great extent, I do agree that design documents do get obsolete as design (as per the document) changes owing to the very nature of agile development.
However, if we are talking about distributed SCRUM where there are multiple scrum teams involved in the same story, design document does help in terms of making sure that design of user stories had been thought through carefully and agreed upon by different developers in different SCRUM teams. Thus, it makes much more important to understand what would it take to write winner design document for complex user stories which takes lesser review cycle from the different stakeholder for approval. In my experience, this has been a concern of technology stakeholders on customer end that they do not get a quality design document from software engineers working from offshore (or different locations) for various different reasons. On the other hand, when speaking to the software engineers, they say that they have provided all the details including various different diagrams such as class and sequence diagram. What more than they would have to do? Well, quite a set of valid concerns from both parties, customer stakeholders and software engineers working from offshore.
The following are some of the must-have sections of a design document irrespective of them being termed as high-level or low-level design:
- Architecture & Design Principles: Even before one start writing the design document, one has to get himself aware of the underlying guiding architecture and design principles based on which he/she needs to createthe design and associated document.
- Design document template: Make sure that different stakeholders agree to what needs to covered in the design document. This is very important to avoid surprises in terms of the details expected in the document and spend time back-and-forth for getting further information.
- User Story description: First and foremost, describe the user story taking into account, the associated business processes and related scenarios. Mind you that you should try and avoid mentioning technical details in this section.
- Solution detail: Describe the solution at a high level mentioning about involved services/modules/components (functional) & their responsibilities, messages flows, exceptions & related flows.
- Diagrammatic representation of solution: Identify the diagrams that need to be created. This may be decided based upon key viewpoints associated with the design. For instance, in some solution, there is a greater impact on the data model design. Thus, one should present data model and class diagram and describe the changes. In other solution, message flows get impacted. Thus, one should draw one or more sequence diagrams. In yet another solution, the deployment and related configuration gets modified. Thus, one should present a deployment diagram to describe the solution. Plainly speaking, it may be incorrect to specify a set of diagrams which may prove important and necessary for all kind of solutions. Thus, following may be some of the diagrams to have:
- Class diagram
- Data model & entity relationship diagrams
- Sequence diagram
- Integration diagrams (Inbound/Outbound communication)
- Deployment diagrams (networking view)
For sequence diagrams, one tool that I have found very handy is websequencediagrams. It has proved very handy for the developers as developers need to write a set of instructions representing interaction between the classes/interfaces and the diagrams get generated automatically. Thus, if you are facing challenge in terms of developers facing trouble drawing diagram, try this tool and I am sure you would be very happy. Also, out of the all of the diagrams, if you want to choose one diagram that could serve multiple purpose, you may choose sequence diagrams.
Provide a textual explanation for the diagrams.
- Exception use-case scenarios: From reliability perspective, a solution may as well have failure scenarios. Thus, one should accommodate all the failure scenarios by describing enough details. This is an area which does not get much attention but is equally important from the perspective of delivering reliable software.
- Implementation details: You may want to include code snippets around components (classes/interfaces) and configuration details matching the solution design. However, the implementation detail section is not that important and is a nice to have thing as the implementation is liable to change once you get down to actual implementation.
You may also ask questions such as when do these design documents need to be generated in Sprint Scrum approach? I have found some of the following as relevant fact in this relation:
- In the sprint pre-planning phase, the SCRUM team identifies the story which are complex and which may need design document. Generally, a story of size 1 or 3 points may not need the document. Only the story of size, 5 points, could need the design document.
- The sprint planning should include a task for design for each of the stories (at least complex ones – size: 5 points).
- When developers get to the design task, this is the time when design document should be started. The design related task related should accommodate the documentation part. Yes, this may prove burdensome for the developers. This is why one may agree to keep these documents very light by including details such as solution description, and diagrams.
Check out my latest book titled as First Principles Thinking: Building winning products using first principles thinking.
- Agentic Reasoning Design Patterns in AI: Examples - October 18, 2024
- LLMs for Adaptive Learning & Personalized Education - October 8, 2024
- Sparse Mixture of Experts (MoE) Models: Examples - October 6, 2024
Hi Kumar, nice article detailing each of the design docs you associate with Agile.
When would you see each of these being generated or ‘handed over/signed off’ during the Sprint Scrum approach?
Thanks for your comments, Mark. The design documentation could be done when developers are working on design related task for that story. Also, it may be good to note that the design documentation should be suggested for complex stories of size 5 points as developers get irritated with the idea of writing document and start equating the whole effort with waterfall based software development model.
Good point. This is one of the worst myths of Agile development. “Working software over comprehensive documentation”, DOES NOT MEAN, “No Technical Design”. I have worked on several successful large scale Scrum projects over the last 4-5 years and all of them had technical design artifacts. We were not using waterfall by any means. We had working, deliverable software every 2 weeks (sometimes daily). Some other thoughts:
– Provide the right level of design to meet the feature. No need to have a documentation for documentation’s sake.
– No need for a complete big up-front design. Design can be iterative as well.
– Sometimes we broke our designs and research-spikes into user stories. We made sure that the design stories had acceptance criteria and treated them like any other work. This helped in cases where we had to prioritize certain technical issues early in the project due to risk or because they where more architectural in nature. Most of the time, technical designs were a task on a user story.
– Do whatever works best for your team situation that delivers working software that meets your customers needs.
– Agile Dev is about delivering quality software to your customers in a predictable way that also gives visibility to your organization. Doesn’t work if you follow all the so-called Agile Rules and don’t deliver.