Hacker News new | ask | show | jobs
by rex-mundi 1698 days ago
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?
1 comments

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.