Hacker News Reader

Comment by adverbly | Hacker News Reader

> How to write a design doc

In over 5 years of dev, I've never been convinced in the value of design docs. I've bootstrapped several large components, I probably only kept up to date a document maybe once out of all those times, and I've never had any regret or paid a price for not having it. You can think up front, draw + share diagrams, get feedback, and have well documented source code without needing to introduce duplication and "englishification" of a system.

I'd love to be convinced otherwise though! Always looking to learn! Anyone care to pitch them to me?

Edit:

After reading the rest of the points, I'm actually pretty convinced this is more of a "how to be <role that provides technical interface with leadership>" rather than "how to be a senior dev". It sounds to me like they're mixing roles/responsibilities here - there are certainly plenty of senior devs without these responsibilities/expectations.

View on HN

Design docs are a heavy-weight way to accomplish 3 major things, roughly in the order of importance:

1) Get feedback from your peers and other teams who need to interface with your design. Your design, or the problem you think you are tackling, could change based on their feedback.

2) Future readers can get a lot of context. Specifically, the design doc documents the trade-offs you considered and chose; this helps future engineers fully understand the problem space before second-guessing major decisions.

3) Leave some trace that you initiated/drove an effort of some design, for career/promotion purposes. You can demonstate how many stake holders/teams your work had to touch, and how difficult the problem & solution are based on various metrics in the design doc (# of ppl that participated in the review, # of services/components your design had to touch, etc). Personally this is my least favourite reason to write a design doc, mostly because I find people write heavy-weight design docs when it serves no other purpose than for perf, and design docs are often.. embelished when they dont need to be.

Instead of a design doc, you can just file a bug, or shoot an email to a wider team, to accomplish the 3 things above. However, it becomes increasing inefficient to solely rely on bugs/email as the # of peers/stake holders increases, the scope/complexity of your project increase, or the communication overhead in your company increases.

I think it really depends on how mature, how complex, how isolated, and how big your project/working group is.

Where does your work fall, and what kind of process do you personally use to accomplish 1,2 & 3?

"Plans Are Worthless, But Planning Is Everything"

So i see the usefulness of design docs to be threefold:

1) Writing it all down in one place. You've got tons of whiteboard meetings, random discussions by the water cooler, random slack threads, ideas you think up in the middle of the night, different asks and different reqs coming in from different teams. It's useful to formally write it all down. And then once you see it all in one place, you can more easily see which parts of conversations you forgot, which decisions that you thought you all agreed on in the meeting but people actually thought you agreed on a different outcome. You can see if there are any contradictory points -- does one decision you agreed on in one discussion actually make it impossible to follow the decision you agreed on in another discussion. You've now got the big picture and see things now you're all zoomed out, that you couldn't see when each discussion was just drilled down into a single component or aspect.

2) Coordinate for review. So now it's all written down, and everyone can go through and see if there's anything that they missed. Are there actually any blockers in here? You can now send it out to all the concerned parties and they can make sure that you didn't miss anything, that all concerns and asks are being properly covered. Are all the original requirement actually being handled by this design? How long is this actually going to take now for all the involved teams and people to do. Much easier to do when you've got a complete list of everything you need to do.

3) Documents your original intent. So now you're off and implementing it all, and of course you end up building something completely different from the design doc. But it's still important to go back to it and be able to see, what were all of these original concerns and blockers and worries that we had? The design doc says we made this decision because of this showstopper, we ended up doing it a different way, but did we properly account for that in our final implementation. Why did we even want to design it this way in the first place, does that constraint still hold today, and will our end result fail because we ignored it.

Did you receive many components bootstrapped by someone else?

I’ve picked several projects along the way and just having one or two ADRs helped me so much. Sometimes a piece was not working so well, but without knowing why it was made that way made it really risky to just decide on a change.

Like code comments and any documentation in general, design docs aren’t best for telling what something is/does but why it exists, why alternatives were discarded, why apparently suboptimal behavior was chosen and so on.

From my understanding, that is what architecture.md is for. 1 doc to describe the current state and reasons for it, rather than 1 doc per change.

I write design docs frequently. They can be anything from two to about ten pages, outside of formal systems like aircraft. They need to be short to be readable.

The point of a design doc is to get feedback on the design and to keep a record of decisions made and why they were made. That’s it. It isn’t supposed to stay up to date forever - your code should document that instead.

Once you get feedback on the design, the doc has served its purpose - archive it and move on.

You’ve just ticked several several items on that list and asked for help understanding another (an act which also earns a tick).

Reply on news.ycombinator.com