Effective written communication for software engineers

Before I started at Google, I thought it was all about cranking out code, building cool things, and basking in the glory of cool-nerdy-esque achievements. I couldn't have been more wrong.

Turns out you need to work with other people ??

And that means

• communicating complex technical ideas
• planning for a big technical project in advance
• building alignment with multiple parties
• getting your management onboard with big investments

Comes into picture n-pagers and design docs ??

Every engineer has to write one. Senior engineers –?in fact, pretty often. A good design solves some very specific problems.

• Without one or one too late –?you spend longer on verbal discussions, there's chaos and everyone's confused.
• With an unnecessary one –?you just waste your and other's time on what could just've been a quick meeting, an email.

Lifecycle of a design doc ??

1.Engineer decides to write one. Why?

• Align on choices: they're designing a new or modifying a system and there's many design choices to be made –?architectural decisions, API design etc.
• Bring clarity: there's large number of changes in a system that are need for a new feature and it's not clear what all needs to happen.
• Document choices: we want to document why certain choices were made for future generations. That will aid future evolutions of the systems.

2. Engineer does a bunch of design discussion and then writes the doc.

• Start with writing "headlines" and bullet points of the doc. Get your tech lead to review that first to ensure you have coverage on important areas and topics.
• How to write a good one? More on that below.

3. Engineer sends the doc out for review (to stakeholders, team, tech leads etc.)

4. Reviewers leave comments. Engineer iterates upon design doc with new information.

• Critical phase to get feedback from relevant parties (system owners, end-to-end experts etc.)
• Make sure to respond to all comments nicely. Reviewers are spending valuable time reviewing your work and ensuring your endeavors are successful.

5. There's a "review" meeting.

• Everyone gets together, discuss 3-4 big topics and go home with action items and decisions.
• We typically don't "present" the design doc in such a meeting. Expectation is that everyone has read the doc in advance and we use the whole time for discussing relevant topics (decided by the design author and a "moderator").

6. Design gets implemented, launched and doc is forgotten.

• Docs are outdated the moment they're reviewed. Try to keep them updated, at least with big differences, if possible.

Anatomy of a design doc ??

Follow this simple template to achieve maximum information conveyed per page.

Objective: what is the overarching goal this project/doc aims to achieve.

Goals/non-goals: scope and non-scope of the design doc in terms of systems, user journeys, functionalities.

Background: quick history, additional context for the readers. Reference to other docs.

Requirements, assumptions, constraints

• Functional/non-functional requirements.
• Assumptions (such as previous decisions, simplifications that will carry out through the doc).
• Constraints in which you're operate (some systems have limited support, there's aggressive timelines, etc.).

Overview: High level design with a component diagram and a few bullet points. Reserve sequence diagrams and details for the next section.

Detailed design: This is where to cover all areas of the design in detail. Use diagrams (components, state machine, sequence diagrams) to simplify understanding. Avoid going into too much detail (such as exact code API changes).

• This is where you list you design choices. They're often pivoted around a question. Such as "should Actor entity model merchants and purchasers?".
• Followed by choices such as "option 1: reuse Actor entity", "option 2: define a new Merchant entity".
• For each option, list down tradeoffs (pros and cons) and considerations. Mark your preferred choice.

Appendix: This is where you put non-controversial decisions and other details that maybe of interest to only some readers.

How not to suck at writing design docs ??

I have written shitty design docs. You have written shitty design docs. Every one does at one point of time or another. I took a look at my old design docs to find why they were shitty and here's what I discovered

• I wrote the doc for everyone (for my Director to the intern who hadn't even joined the team). Meaning? I was rambling too much, providing too much context than needed.
• I was afraid that my doc was "too small". Afraid that the work I was doing wasn't worthy of a design doc and somehow I had to justify filling up pages.
• I was putting code snippets in the design doc to show how I was going to implement it. The comments that I was supposed to receive in code reviews – my "design doc" was now full of those.
• I had huge paragraphs of my thoughts "puked" in the doc. Nobody wants to read a novel. Just stick to bullet points please.
• My design docs were 25+ pages long. Who's going to read that? I was putting in non-relevant details (such as non controversial decisions/choices in the design doc). They can go to appendix or another n-pagers.
• I thought comments from others were a bad thing. From getting defensive to outright just ignoring comments, I've done it all. In fact, my peers and seniors were just giving crucial feedback.
• I hated editing. I wrote something, fell in love with words, and had a really hard time removing things from the design doc. Why not just start with something sparse and then add details as and when required.
• I had no practice. Writing, editing and organizing thoughts into words comes with practice. As long as you're retrospecting to see what you could've done better. Read other's design docs to get inspiration.

In summary, writing design docs is an essential skill for software engineers. Effective communication is one of those things that stands out in good engineers. It comes with practice and retrospection.

With that, adios and happy writing!