19 Comments

I've found Architecture Decision Records (ADRs) to be a great way to document how and why a decision was reached within a codebase.

Unfortunately, design docs are underrated.

Great post, Jordan! 🙌

Expand full comment
author

I love ADRs too.

Do you do the ADR after the design doc or in replacement of it?

Expand full comment

Most of the time, we did both. If we wanted to introduce a new process, refactor something, etc., I first do a Technical Proposal. Later, if it's accepted, I document it in more technical terms in an ADR, also mentioning the proposal, so it's clear why we needed it in the first place.

Expand full comment
author

Ahh, makes sense. Thanks for sharing your approach, Petar

Expand full comment

Couple of things I would add to consider depending on project:

- Handling deprecation as part of design doc

- Security and Compliance if needed

- Data related section if needed

Expand full comment
author

Yes, definitely agree Junaid.

I notice many of those sections get added over time to the company doc, normally through postmortem action items to make sure they get considered 😄

Expand full comment

Thanks, Jordan for including my comment!

After reading the entire article I see the second section as extremely important too!

I remember a design review where we had a Principal Engineer in the meeting, yet we were doing a team review and the team was having all the attention. The poor Principal Engineer was just in the background, wasting his time.

In some kinds of documents (e.g. postmortems) the writing style is important. In others, making comments about the writing is just a distraction.

Starting the review meeting and telling people what's the purpose of the review can save so much time

Expand full comment
author

Yeah, that's been a huge "win" for me on leading meetings.

Reminding people at the start what it is we're meant to do. I find that it helps keep things on track and builds confidence from everyone there that we're there to achieve something.

I notice a lot more "This felt productive" comments at the end of the meeting

Expand full comment

Awesome write up on design docs or technical specs as I’ve called them. Senior engineers will have to write these, so it’s important to learn what to include and how to write a through doc.

Little things like the “Out of scope” section you included are key to a project’s success.

One thing I would add is a milestones section. It really helps to break a large project down into smaller chunks.

- It allows us to ship incremental value to users.

- Helps us estimate better (smaller chunks are way easier to estimate).

- Gives us a start at user stories and further breaking things out into tickets.

- Aligns the team around the main goals.

Expand full comment
author

Totally agree with the milestones section and the reasons for it.

I actually do have that in the list of the various sections--its just not in the screenshot since the document cant fit in a single screenshot.

Thanks for sharing your thoughts around this, Caleb. Love to hear it straight from a tech lead :D

Expand full comment

Gosh I read it and missed that. 🙃

Glad we are on the same page!

Expand full comment
Jan 28·edited Jan 28Liked by Jordan Cutler

Design docs -> very important for alignment inside the team and also between different teams! Like the idea of getting the individual feedback first. That increases your overall confidence in the spec before you make it public for everyone.

Thanks for mentioning my article from the last week!

Expand full comment
author

Thanks, Gregor. Well said and totally agree.

Yes! Loved that article. Great writeup on a super important topic

Expand full comment
Jan 31Liked by Jordan Cutler

The first is a great point and is pretty much the same with PRs. Long ones are either LGTM or take ages to review. 😄

Admittedly, I never wrote such comprehensive design docs, probably because I either worked in smaller teams where we would plan out the thing inside a GitHub issue or because it was client work. In those cases, I was the only one making decisions. But even then, I wrote at least a memo about why I did specific things. Documenting never hurts.

Thanks for sharing this. If everything goes well, I’ll soon present design docs to a bigger team! 🤞

Expand full comment
author

Yep, agreed on being concise haha.

Thanks for sharing, Akos.

It's cool to hear about your experience and also nice to know we have a similar background too. I've been on small teams a lot lately, so design docs might be a formality in that case after discussing 1:1 with someone.

Still, for the cases where it's not, wanted to have this article for myself and others :D

Expand full comment
Feb 5Liked by Jordan Cutler

It happened to me. I forgot why we made a specific decision two years ago, so I also found them helpful in smaller teams!

This article was great for me right now because I'm looking to join a big team soon, and coming from the startup/move fast, break things/ world, I find it helpful to see how things work in the corporate/big team world.

Expand full comment

Can you share some good examples?

Expand full comment
author

Of a design doc?

Expand full comment