71–80 of 191 posts
Design docs help you understand the project, identify dependencies, and avoid repeating work. Then they leave a trail for future engineers of the thought process that went into the code.
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.
Does duration really measure depth of design?
I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible. That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents. These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and deliv…
I think something people need to be aware of is that the engineering culture at places like Google is extremely different than, say, a bank. Design docs work well for Google because it has decentralized, independent engineering teams composed mostly of reasonable people, with few or no mandates from outside their teams. They tend to fail at companies with underperforming, micro-managing, and/or overreaching teams (e.…
I have to say that this is not uniformly true, I've worked for a few financial institutions, and usually follow some sort of design process before embarking on any sizable work (as mentioned above, I find the RUP process to be a really useful framework). More often that not the design process is usually welcomed because people are happy that someone is willing to create a holistic view of the problem (from stakeholders down to db schema and class diagrams). The process helps with project management, identifies stakeholders and describes the support requirements after transition to prod.
Banks actually love somebody to detail all that.
In a few cases I'm aware of, my design docs are still referred to years after I've moved on since they capture the most important thing that everybody forgets - basically the 'why' that certain decisions were made, and the alternatives rejected.
A good architecture diagram never goes out of date either :)
Now that I wrote the above, it's a bit sad that there aren't many design docs for open source software, even ones that originated from companies with good design doc culture. Where's a doc that discusses alternatives considered and rejected for kubernetes or grpc?
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?
I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.
https://www.industrialempathy.com/posts/design-doc-a-design-...
A fun activity if you’re a Googler is to go read ancient design docs, like the original pitch for bigtable. They are pretty short for the most part, and they were written by the legends. These are the Federalist Papers of your company, they give real context to how the company arrived here. In particular I always enjoyed reading the jarring parts were they describe something that definitely did not make it into the i…
Great article. I spend a lot of my time writing design docs these days. We derive a ton of value from it. The projects I work on are typically collaborations with several developers. It is important to all have the same vision for what we are building. A good design doc is a vehicle for a team to sync their mental models of the thing they are building. We also often have many other teams (security, infrastructure, op…
This brings to mind the 1-10-100 rule. It takes 1 unit of effort to fix a problem in design It takes 10 units of effort to fix a problem during development. It takes 100 units of effort to fix a problem after going live.
Earlier quoted context omitted.
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.
Never lived in a house with a design flaw? My first flat had a toilet that blocked the door from opening fully. It was correct according to the blueprints.
Earlier quoted context omitted.
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.
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…