61–70 of 191 posts
Then we get to see how well it works, not leave it up to imagination.
Related: https://www.joelonsoftware.com/2000/10/02/painless-functiona... My opinion: If you don't specify things in a separate document in the form of text and pictures, then you end up doing it anyway but ad-hoc. Your "non-spec" now leaks into multiple tools and channels that likely don't talk to one another: emails, instant messages, file storage, notes, phone calls & discussions (AKA in your head/memory), Trello/A…
Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of c…
Does anyone have any insights on how to make the reviews more constructive + quicker?
Earlier quoted context omitted.
>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 specif…
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.
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.
Frankly I think Amazon has a even heavier design culture. The designs for a new project (e.g to be launched at reinvent) could go as long as more than half year.
Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of c…
My experience has been that writing the design doc is not as controversial, as much as the review process. Does anyone have any insights on how to make the reviews more constructive + quicker?
1. Start with defining the problem you want to solve and identify the stakeholders. Then meet each stakeholder 1-1 and get approval.
2. Propose an API. Then meet 1-1 again for approval.
3. Make a high level arch diagram. Seek approval again.
4. Proceed with actually writing the design doc and begin the formal and official review.
Points 1-3 could be done in a week if planned well and will make the design doc a lot less controversial and get you through the review process quicker
Earlier quoted context omitted.
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.
If 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.
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.
Earlier quoted context omitted.
Same could be said for code, right? It's a great idea, but in 30 years we've never seen code done well. "Well" is a slippery word.
But code actually works (eventually, usually). If you don't have code, you don't have software. If you don't have a design document... it's usually the same as if you do have a design document.
Earlier quoted context omitted.
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.
If 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.
My first flat had a toilet that blocked the door from opening fully. It was correct according to the blueprints.