Principal Eng at Microsoft. Ex Google, Amazon | I write about my learnings at big tech, link in bio
Amazon has a strong writing and consensus driven culture. Before starting a project, you’re expected to write a detailed proposal/design document and get consensus from all your stakeholders. Some might find it tedious, but I have found that design discussions do need to happen because trade offs are a central part of software engineering. You can either have the discussions upfront based on your document OR You can try and make design decisions in code review comments. 🤷♀️
Let me explain how things happen in practical life: (Real life scenario) Make a bug fix due to multithreading of 1 line: 1. Writing culture: Make design doc of 1 page, Spend a week on driving consensus, Address comment, Last day some one will point an issue and in the end we take 1 month for the proposal to go through. Make a retro and postmertam etc Total time to fix bug: 1 month and customer suffer for 1 month 2. Other company: Bug found in morning and fixed in evening, if not fixed, try again Time taken: 1-2 days maximum. No customer suffering. Every culture works on some context. Context where speed over acuracy is needed this culture sucks.
Discussions do need to happen but does the writing of a whole document need to happen at the beginning?
Bhavana Hindupur I have personally found the idea of putting together a document to be quite useful- for myself as well as all for stakeholders. When you write down, in complete sentences, what you plan to do, you get clarity in your thoughts. It is difficult to write a complete sentence with half-baked thoughts and then read it yourself comfortably, later on. This happens a lot with powerpoint bullet points. You can gloss over an idea without fully articulating anything concrete. It becomes easy to scrap ideas that aren’t going to work with the document writing process. You never end up creating the code review this way for things which aren’t going to fly.
I think having discussions up front with all stakeholders and getting some of the key decisions in writing is great. How do you handle changes that inevitably occur? Do you keep all design documents up to date 100%? Do you add addendums? Something else? When changes occur, how do you communicate them to the entire team? The biggest downside I’ve experienced to having too much detail in the design document is that the documentation isn’t kept up to date or if enough resources are allocated to update the documentation, the changes are not communicated well to the entire team.
OR you can work together on the problem incrementally, using feedback against the real world to inform your key design decisions along the way. Far better than big design upfront.
Hot take: Exploring ideas first > perfect planning initially... At the end of the day, you can't predict all trade-offs to be made at the beginning of a project. You'll still have to make design decisions on PR comments at some point. I personally believe planning has a lot of value, but the pressure of having to have a fully formed idea form the beginning can stifle creativity. I find it more valuable to dive in and explore the idea first, then get consensus.
Staff SWE at HubSpot • Helping you become Leader in Tech Career and a Balanced Being in Life • Author at Curious Soul’s Corner Newsletter - subscribe now!
1moI’ve worked at Amazon for 6 years, so I can relate to this. However, having worked outside in multiple companies, I now feel Amazon culture is too restrictive sometimes. I’d agree that trade offs need to be discussed but I would prefer consent over consensus. With consensus model, we are always seeking permission from multiple blocking parties while in consent model, we ask if anyone has any issues and proceed with small incremental steps in safe way possible. Second, a pure written doc without much prototyping has been counter productive for Amazon and has led to promotion drive culture.