alt Hacker NewsAuthor here. Happy to take any feedback about this post.
I learned to write design docs at Microsoft and Google, and I thought they both had good culture around docs that hasn't percolated out as well as other engineering practices at those orgs. I haven't seen a thorough explanation of how to write design docs, so this is my attempt to externalize what I've learned about writing them.
Replies
So I tried this and it failed miserably.
The documentation became the bible, and although I tried to keep the design goals at the conceptual/logical level the following would happen the moment the implementation started:
1. This is ambigous the docs need updating, please refactor your design 2. This doesn't work as the doc stated why did you get this wrong 3. The requirements have changed you need to update it
The burden to get "everything right" was absolutely lumbered of me, and the document became an easy finger pointing exercise, even if blame wasn't intended by those launching the critique the burden of "owning" the doc and the consequences of the doc was real.
Now there's a good chance that I am just a shit documentation writer, I can accept that, but honestly I feel like for the vast majority of organisations this just falls into another step of the waterfall pattern, which just doesn't work.
How do you handle this? What did I miss?
This is good guidance, but what do you have to say about convincing your team of developers to live it out?
I've found that developers usually like writing code and avoid contributing to documentation. For some, it's actually scary because (edit: for them,) high quality writing is harder than high quality coding, and it can be avoided quite a bit.
On the project side, it's rare for the implementation and verification stages to not consume all the budget and more, and delivery creeping past the original optimistic date. So there's no time or money to spend on documentation.
The combination is that even with your great advice in hand, it's hard to navigate to really solid and comprehensive design documentation underpinning the products.
How are design docs changing in the agentic age?
Good read, although the document would be very lengthy if I am to write all the sections in the articles. I sometimes break down the design doc into multiple design docs.
- Manager doc : Summary(Background + Objective), User Story (Scenarios), High level architecture, open questions, task break down + timeline including other teams' tasks
- Engineering Architecture doc: Summary, Glossary, Goal (Functional + Non-functional + Non-goals), More detailed architecture & components between, open questions, tasks break down + timeline
- Engineering API / Database design doc: Similar summary + link to architecture doc. More detail information on API (eg: input params, output params, example client code) + database design (eg: database type + fields), open questions
Each doc is to be read within a single meeting. The shorter doc helps narrowing down the discussion scope.
Disclosure: I worked at Amazon where there is a typically 1 hour meeting session with the first 15-30 minutes dedicated to reading. It's probably why I multiple short docs over a single design doc. Telling people "Today, we'll read section 1,2,3,5,8 of the doc" didn't really work.