6 ms·
>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
by learc83 6y ago
>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.
- cameronbrown 6y agoI 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.
- learc83 6y agoYes 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.
- sgt-serverless 6y agoDangerous seems a bit extreme. If developers aren't builders, then what are they?
- DEADBEEFC0FFEE 6y agoModels are always imperfect.
- shuntress 6y agoThat is true but if the analogy is too imperfect then it won't express the right concept. A bad analogy is like a leaky screwdriver.
- gowld 6y agoAn analogy is a blueprint for an explanation.
- nickbauman 6y agoThis 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.
- supahfly_remix 6y agoIf the design is the code, then what is a bug? There is a separate model, whether written down or not, of what the code must do. That is the deaign.
- sanderjd 6y agoI 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.
- nickbauman 6y agoMuch of this is captured extremely well in Fowler's The New Methodology. https://martinfowler.com/articles/newMethodology.html https://martinfowler.com/articles/newMethodology.html
- learc83 6y agoWhat 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.
- javier10e6 6y agoI agree wholeheartedly. The best software documentation is the an actually well written software module + test that explains its functionality.
- TeMPOraL 6y agoLet's not forget about comments. 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.)
- mkoubaa 6y agoin summary: what -> naming convention why -> comments how -> tests I wish this was more commonly shared and understood
- fsociety 6y agoThe 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.
- learc83 6y agoAt 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.