>If code is the bricks and mortar, then these docs are the blueprints.
That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints.
You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens.
The problem is that the only way to get to that level of specificity is with code.
Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.
I mean, you're right... but the goal of an analogy isn't to be perfect, but to be a rough mental model to quickly express a concept. I think it's fine.
Different jobs require different levels of abstraction and design docs fulfil that role for software engineers.
Yes models can be helpful even if they aren’t perfect. But not only is this one too far off to be useful, it does more harm than good. The expectations that happen when people (specifically managers) start thinking of design docs as blueprints, software architects as architects, and developers as builders are downright dangerous.
This is something that should be taught to folks while they're still in school. The "blueprint analogy" has baked in the idea that there's a "design phase" and a "construction phase" and that these are often discreet parties.
Nothing could be more incorrect when it comes to software. In software, the design is the code. The compiler/interpreter are the construction of the system.
> In software, the design is the code. The compiler/interpreter are the construction of the system.
That's IMO a pedantic view. Yes, ok, but when I design software I describe it's high-level characteristics, more like describing the plot of a book than the specific words in a book and the what the characters say to each other.
I'd say there are many levels of design. Code is the last.
Your design can look very good yet be seriously flawed when you actually write the code. Designs (blueprints) civil engineers use are based on many years of practice that are enshrined in engineering codes sometimes going back thousands of years. Key issues in the design like the way forces interplay, are amenable to mathematical analysis. The only checking we can do of UML-like diagrams and written "specs" is peer review. Not the same at all.
What happens when there is a flaw in the design? There's another higher level of design on top of that, with a platonic ideal of the design unknown to humans at the top? Turtles all the way down.
Each stakeholder has a different "design" in mind, and until you actually get specific there is no design, there's just a nebulous, incomplete list of requirements. And if you do try to get specific enough to be reproducible--you're writing code.
None of this is to say that design docs are worthless, just that they can never be specific enough to function as the actual reproducible design the way blueprints would. Thinking of them that way is harmful.
Reproducibility is just a side effect of lack of specificity, which is the major difference and the entire point of my critique. Design docs don't tell you enough to actually build the thing you want to build.
Assume you hold the view that a design document provides all the information necessary to construct a piece of software without any further design work.
Construct a software development methodology around that assumption. Now remove that assumption, and think about the practical consequences for a team who doesn't realize that the assumption is incorrect until after they have started implementing a design document.
Imagine what would happen if you hired an architectural firm to draw up some blueprints for a house, and then midway into the construction of the house it turns out that the assumptions made in the blueprints are wildly out of sync with what's possible to build.
It is significantly better for everyone involved if management goes into the process knowing the limitations of design documents and up front design.
For more concrete example of the practical problems see the history of the debate between iterative and big design up front methodologies over the last 30 years.
I think they were using "design" as akin to the blueprint to the building. I totally agree with them that in that sense, the code is the blueprint, not the building. The execution of the program is the analogy to the actual construction: the builder (computer) takes the blueprint (code) and builds the building (executes the program) based on it. The power of computers is that the "building" (execution) part is essentially free and infinitely reproducible. But the creation of the "blueprint" (code) is still labor intensive.
The right analogy for design artifacts really is to the higher-level vision definition for a project. Engineers don't just show up and start drawing blueprints; one or more people come up with a purpose and concept for a building project, brainstorm approaches, evaluate trade-offs, come to some consensus on the right direction, and only then start working with engineers to start creating and iterating on blueprints. This vision phase is where design docs fit.
"The design is the code" does not follow from the idea that design and construction are not separate things in software.
The thing to take away from that idea is that the design doc is not law written in stone, but a base for changes. It keeps your design honest on the high level. If you end up clashing with reality, and your design doesn't work out, you can backtrack to the design doc and refine it as necessary.
In short, the design doc should be a living document.
I think what you're talking about here is an "intention document" not a design document. Design is about planning. Which implies you define things in detail with steps and techniques. Intentions are about what you want to achieve. Very different.
The design doc is definitely the plan. But if the plan doesn't work when faced with reality, you need to change the plan, and therefore also the design doc.
> the design is the code.
And this is why Software development should never be considered engineering. Architecture is important and in the construction phase there are changes and revision to the design that are captured and formally reviewed.
In software, if the code is the "design" then it should be a priority for computer science to agree upon a standardized design representation (UML) that can be generated by the compiler/interpreter, along with code coverage and static analysis.
The issue here is that there has not been adoption of formal rigor of design and definition of implementation into code of proof of correctness alongside data structures and algorithms appropriate to the domain state. Add in understandable and usable build and testing tools.
The infrastructure is there, with CI/CD, and a repository of github/gitlab, team foundation, cvs code and say something like a successor to GPT3 to do the grunt work of analyzing code to determine optimal patterns of implementation vs existing code bases and development sprint branches.
Even compiling code or "making" it can be a crapshoot for extremely senior and competent developers.
The Code is the Design and the design uncovers good or bad written code. GoF design patterns were modeled after well written code. Anti-patterns (the swiss army knife is my favorite) are bad written code.
The analogy actually makes sense if you’ve worked manufacturing things from blueprints.
If you hand one complex blueprints to three random construction firms, from a distance you’d get the same result, nearly, but up close a lot would’ve changed during the project.
There is a reason why engineers are required to inspect the project at some interval and perform quality checks.
At some level sure there will be differences, but for the end users, unless something went wrong, they won't be able to tell much of a difference.
Blueprints for a house are much, much closer to being reproducible than design docs for a software project.
If you give design docs to 3 separate dev shops, the end results will be wildly different.
>There is a reason why engineers are required to inspect the project at some interval and perform quality checks.
It's true that there is still some room for interpretation because blueprints are still a model. But most of what your talking about is because people will cut corners and not follow the specifications, not because the specifications aren't there.
A well written piece of code will only tell you what it does, a good suite of tests will teach you how to use it, but only natural language documentation - be it in comments or separate documents - will explain to you why the code exists in the first place, and why it looks the way it does.
(As for "self-documenting code", unless a lot of your functions contain the word "because" in their name, the code isn't really self-documenting.)
That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints.
You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens.
The problem is that the only way to get to that level of specificity is with code.
Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.