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. However, if we are talking about distributed SCRUM, design document does help in terms of making sure that design of user stories had been thought through. 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 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. 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 that they would have to do? Well, quite a set of valid concerns from both parties, customer stakeholders and software engineers working from offshore.
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 document, one has to get himself aware of the underlying architecture and design principles based on which he/she needs to create design and associated document.
- Design document template: Make sure that different stakeholders agree to what needs to covered in the design document.
- 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)
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.