Hacker News Reader

Comment by tommiegannert | Hacker News Reader

While working at Google, I came to appreciate design docs. They're a way to help think through the system design, and help communicate the goals, decisions, etc. at a high level. It also provides experts with a place to put in checklists, to encourage me to answer how e.g. privacy is affected.

However, what I missed was a "problem doc". Something for when I just have an idea for a problem to work on, but forcing myself not to share a solution. Something that triggers brainstorming in the reader, and perhaps the right place to also ask "is this the right problem?"

(The article itself seems to just be about https://en.wikipedia.org/wiki/XY_problem)

View on HN

Did the Google design docs follow any guides on how to structure/present the information and how to draw the line between too little and too much detail?

There is no standard for design docs at Google and everyone is free to experiment, but most commonly used templates usually share the same ideas. My favourite is to write a green doc and a blue doc. The green doc is typically a "one pager" (basically always 2 pages at Google) and it typically never discusses implementation details. It's mostly about why we need X and the goals and non-goals of the project. Once your green doc is reviewed by your teammates, if everyone's happy, you write a more in-depth blue doc where you'll probably design the protobufs and interfaces, draw the system architecture, make framework choices and trade-offs, design metrics for monitoring, think about scalability, alternative approaches, and maybe even outline a timeline for the project if you're feeling ambitious. This, too, will go through a few rounds of reviews until everyone is satisfied. The green doc is significantly less investment than the blue doc, but it's still some investment (say ~1 SWE-week of writing the first draft + reviews + future iterations), so this pattern only makes sense if your project is complex enough. If I'm just adding things to an existing project and I still need a design doc reviewed by other people, I'd probably just write one design doc.

Reply on news.ycombinator.com