Documenting the project is a critical part of the design process: since there are both business and technical audiences, it is not easy to draw up something that can look appealing and clear to the business and provide both enough implementation details for the technical people.

For this reason, the traditional top-down approach is to write:

• the High Level Design Document: this document is mostly business oriented, describing the project in business terms, highlighting costs, benefits but it must also provide the bare minimum level of technical details to have this business-oriented people be able to figure out the final outcome, as well the necessary details to start writing a more detailed technical document - Personally, I like the approach described in the NASA Systems Engineering Handbook: according to them, writing the High-Level Design Document gets improved and updated while the technical documents that cover and address the low-level requirements get written, since only during that stage a lot of hidden problems are unveiled and addressed: this enable also to provide more accurate estimates by the way.
• the Software Design Document: this is the document actually used to implement the project, so it must be clear enough and provide enough details to enable people working on the project's implementation to work as much independently as possible, avoiding pointless meetings that only lead to to waste their time and delay the project final delivery. Mind this document is quite agnostic and provides only a few hints about deployment - deployments are managed through a different document (each deployment is an instance, so a dedicated document is necessary). If the deployment is small, probably a diagram with a few details and a testing report are enough, but on huge deployments, it is necessary to write a Deployment Plan Document.

Agile purists will object that the top-down approach is superseded by bottom-up and that Agile transferred this part of the job to teams. That is the theory - in my personal experience the Agile bottom-up leverages on a lot of meetings necessary to make people aware of what's happening - this works nice with small projects, but it tends to become less effective with mid-size project and does not work at all with big projects. The outcome of that approach is having poorly written documentation, components designed using different styles of the involved people, that may hide unexpected later problems (especially from the operating or maintenance point of view) because of the limited point of view available to them. In addition to that, on big projects it is not as cost effective as they say, if you consider the cost of the increased number of meetings and the number of participants - remember that the cost of a member is its actual pay plus the missing earnings for not having him producing. So long story short, ... I've nothing against using bottom-up design in Agile, if it is properly used in the correct use cases, but blindly using it will only lead your projects into a mess: as someone else already said, "Agile comes with no brain, please use yours".

Writing both the above documents is a task that is not easy at all, so I wrote this post to provide a template with a use case of a SDD Template Software Design Document For Kubernetes Service - more specifically, a microservice of an existing service.

As you will see, this document leverages and is in compliance with the company wide Software Design Document: this global one is used to provide taxonomy, standards and best practices every project in the corporate must comply with..

Read more >