Best Practices For Writing Engineering Reports

3-step framework to write review-ready design docs every time as a software engineer. (Based on my learnings of over a decade in Engineering Management & reviewing 100s of design docs, this works like a charm every time) 1/ Start with a skeleton, write these: ◄ Metadata (Title, authors, status, date, reviewers, approvers) ◄ Context and background ◄ Problem statement ◄ Summary or tl;dr (Optional) ◄ Proposed solution details with tradeoffs and selection rationale ◄ Other alternatives considered ◄ Failure modes of the proposed solution ◄ Open Questions ◄ References (Optional) 2/ After the skeleton, fill in the content under these headings. -if there are sub-sections, add sub-headings. -provide examples and sample calculations. -use bullet points and lists wherever applicable -include architectural diagrams, graphs and tables. 3/ If the document is large, put a summary after the problem statement. Start with the skeleton, take it one step at a time, and before you know it, you are done! Remember, a good design doc: -helps understand design decisions and implementation details -helps in identifying potential issues and challenges early -gives a clear understanding of the architecture -serves as a reference doc during the project While you write and review, make sure your work follows these guidelines. I know writing detailed docs doesn’t come naturally when you’re focused on problem solving. But it’s an essential skill you have to learn to level up. just follow a simple procedure, practice and you’ll get the hang of it. Also While writing, just remember: - Think like your reader while writing - Take a break and read it with a fresh mind - Keep it as clear, simple, and brief as possible - Iterate over your design doc a few times and polish it - Get early feedback from 2-3 people and incorporate it in your design – P.S: System design interviews are one of the biggest deciding factors for mid-to-senior engineers. They test how well you can make trade-offs, balance constraints, and architect scalable solutions. I am taking a System Design Webinar next Monday, where I'll be covering: ✅ How to approach system design interviews strategically ✅ Common mistakes candidates make and how to avoid them ✅ The trade-offs that actually matter in real-world systems ✅ How to structure your answers to stand out Here's the link to register: https://lnkd.in/gM3TvVFn

The best way I found to improve my writing at Amazon - I ask myself: Does each paragraph have numbers? Should it? No numbers? This might mean that you are making statements without data or metrics. Sometimes this can be okay - citing a customer anecdote in detail, outlining the general problems customers face in a "press release"-style of communication, or describing how a technical solution works. However, most of these are better with data: "In the research study Eugene struggled to find how to apply his discount code to his order" gets better with "Eugene spent 2 minutes and tapped 14 buttons or links before giving up on applying his discount code". Or better still adding color to how this applies more generally: "we do not have metrics for this activity on our app to appreciate how common Eugene's experience is, we will investigate and propose a solution by DFD 10-Oct." Sometimes lacking data makes us ignore a critical problem: "our slow Build/Test/Deploy times are making engineers frustrated and slow" sounds bad, but also sounds expensive to fix. Vs. "each commit (325 total in H1 2024) of Build/Test/Deploy for each of the 21 engineers in our codebase took 25% longer YoY (5 hours vs 4 hours)". Holy crap - we need to spend time on fixing that problem now! For the next paragraph you write (for whatever kind of business writing you do) try adding numbers where you didn't have them and see what happens. As you progress in your writing you may find it helpful to apply an even higher bar - does each cohesive point have clear evidence? In the most restrictive version of that question you add evidence (numbers or anecdotes) to every sentence. It makes writing way harder, but can make reading and deciding much easier.

The most valuable skill an engineer can develop isn't writing more, it's writing less. Engineers have a natural tendency to be comprehensive. We document every technical detail, edge case, and potential issue. This works great for pull requests, technical documentation, and architectural diagrams. It fails spectacularly when communicating with non-technical stakeholders. Here's what I tell my engineering team about stakeholder communication: • Concise > Comprehensive. Five sentences beats five paragraphs every time. • Put blockers and critical issues at the TOP of status reports. Not buried at the bottom. • 𝗕𝗼𝗹𝗱 𝘁𝗵𝗲 𝗶𝗺𝗽𝗼𝗿𝘁𝗮𝗻𝘁 𝘀𝘁𝘂𝗳𝗳. Your executive contact is scanning this on their phone between meetings. • Action items should be crystal clear. Who needs to do what by when? • Save the technical deep-dive for people who ask for it. Remember: When stakeholders get 1,000+ emails and juggle dozens of issues daily, your meticulously crafted 3-page status report isn't being read, it's being skimmed in 30 seconds. #TechnicalLeadership #EngineeringCommunication #StakeholderManagement