I think if there was a rigid spec, it would work against one of the points made early on in this doc (which I think is worth taking note of):
> Rule #1 is: Write them in whatever form makes the most sense for the particular project.
This is an unsatisfying rule, but I think it's important because each team/problem space/etc. is different and too strict of rules can often lead to documents that may end up being shallow.
However this admittedly doesn't help with this other problem you brought up:
> Also, when design changes - these docs need to be updated.
... but that may be okay given a shared understanding of what the goal of said document is. If the goal is to gain consensus around an implementation (as opposed to it being a living document), the document may have served its purpose by the time that consensus is reached, even if later on the design changes. If the goal is to have living documentation of a system, then maybe the rough format specified in this article isn't correct.
One term I've heard for design documents is that they end up being a piece in a "Decision Log", which has helped me feel less bad if the document falls out of date. These documents end up being more point-in-time representations of the collective understanding/opinions of how a specific project/system was being thought of, and that has its own advantages even if it falls out of sync.
The first points here are absolutely correct. These documents are a way to communicate and get feedback (and iterate) on an idea with a group of people in your organization. Different organizations will communicate differently, and have different needs.
> Rule #1 is: Write them in whatever form makes the most sense for the particular project.
This is an unsatisfying rule, but I think it's important because each team/problem space/etc. is different and too strict of rules can often lead to documents that may end up being shallow.
However this admittedly doesn't help with this other problem you brought up:
> Also, when design changes - these docs need to be updated.
... but that may be okay given a shared understanding of what the goal of said document is. If the goal is to gain consensus around an implementation (as opposed to it being a living document), the document may have served its purpose by the time that consensus is reached, even if later on the design changes. If the goal is to have living documentation of a system, then maybe the rough format specified in this article isn't correct.
One term I've heard for design documents is that they end up being a piece in a "Decision Log", which has helped me feel less bad if the document falls out of date. These documents end up being more point-in-time representations of the collective understanding/opinions of how a specific project/system was being thought of, and that has its own advantages even if it falls out of sync.