Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation - joelparkerhenderson/architecture-decision-record

architecture-decision-record/locales/en/templates/decision-record-template-by-michael-nygard/index.md at main · joelparkerhenderson/architecture-decision-record

https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md

One thing I started doing Sid is to just create a master document of where everything is. It sounds tedious but basically I have a public (within the company) overview in confluence for each project I’m in charge of: where is the design system, where are the meeting notes, etc.

So far I had to use Jira, but I will not define it as a good and efficient way of doing it

Yeah, I think no matter how good you are at your job, you will forget why decisions were made. You’ll forget why smtg seemed important enough at the time that it would lead to a particular decision. That’s human 🤍 
I’m so excited to hear you’re considering adopting ADRs! 🙌🏼

Thats true, every product ends up baking in the style of the designer working on it and as that changes, so do those parts of the product that they touch... i think the most significant impact is the handover and initial stages and wonder whats the best way to make that easier

Ah, I see.. That does make sense and can lead to very messy situations. I do think this is something that should/could be co-owned by EPD as far as what's actually implemented and why. Design decisions are a part of it, but the "source of truth" is really what ends up being built

I’m exploring a way of organising the file in Figma, with comments on post it and some general overview card at the very beginning to create a solid storytelling,

How do designers log design decisions? How does a designer picking up a project from another designer find out why something is the way it is? 🤔

I 100% agree, especially with keeping pertinent information in the actual Figma file. I think cross-referencing also helps though that can quickly become a convoluted mess loll

We had to redo our company website & there were conflicting opinions about which platform / tech stack / etc to use. We looked at different solutions & made certain decisions & months later another lead designer swooped in and made a conflicting decision that changed everything.

What about in house design teams? How do we have make handoffs better in  orgs with large design teams while keeping work agile? Whats the best place for recording this for product and engineering?

I came about this when thinking about version control and sharing WIP for feedback... i feel theres a place somewhere in between where this lies?

It is what makes sense to me. Product/Design rationale should live somewhere, for discussion and documentation. I don't think design tools should be the place for high-level decisions. We use Notion for that at Circle, not the ideal but it works 🙂

Great convo here and I agree that a decision register that affects the product shouldnt sit within the tools and rather be in a place where everyone can see them. Perhaps theres a place for finer details within tools like Figma.

Sounds like a very similar setup! Making effective use of confluence and Figma for documenting in a way that doesn't duplicate info while still maintaining some sort of linkage feels most beneficial with the limitations they both individually offer

Is a good question I still have to find an answer tbh. Since the design decision is usually a mix of design, tech and business, log all this informations can become quite tricky.

What about cross functional teams? Is it duplicate work to make it visible to them if you do it in Figma? What if the person(s) aren't around?

Are project management tools the place we should be documenting that? It does make sense tying them closely but should they live in the same place? 🤔

I agree with you. But I also know from experience that sometimes something that seemed like a good decision 3 years ago wouldn’t be one 3 years later, and sometimes it’s much easier to have an actual record of the decision very clear on the page, not buried in the docs.

I'll also add that there's probably been projects I inherited but then just decided to do my own thing/clean things up to be more consistent with whatever was going on at the present time, so what the original person did effectively didn't matter much

I use a notion/coda page for each project.

Those are great questions! It’d be great to try any tool that would help keep track of the rational/thinking not only execution aka history in Figma

ADRs are pretty great and we do use them. We created DHRs (design history rationales) but its interesting what goes in and its not very consistently used. Theres also a lot of friction involved here unfortunately

I used to carve them into a tree but it became unsustainable

Ok, so I agree with you that in some cases it can feel like there’s hidden micro mgmt / not trusting designers in there, in our case there was something very specific that led me to suggesting using Decision Records in the future..

If I've worked off of something and the owner/creator isn't around, I think it usually comes down to your best guess.. But I don't think I've taken over something and was like "WTF is going on here" if I'm being honest lol

(Me speaking from the perspective of someone who was in PO/PM positions as well in the past)

Basically just to say that in lieu of a designer (like if they leave the company, just as an example) the product manager/owner should also be able to speak to "why is this the way it is" if not someone else involved

It was at a doc company, so we were pretty on top of our docs lol. But we’d usually update in time for our end of the week team sync and share our big decisions with the broader team.

I don't know if this is a dumb question but what constitutes a "design decision"? I would think certain decisions are obvious.. For ex: something that is directly derived from a design system. I guess what I'm wondering is: How detailed would this be (ideally)

I would usually have notes in Figma or supplementary written documentation but probably the best thing is to ask.. Assuming that person is still around, I mean. 

Could also check session notes for crit sessions/things like that

This would live in the same place where the documentation for the project lives (so mainly Confluence for us). Eng also started to introduce DRs/ADRs so it’s not that far off imho to do this for design as well.

I personally intend to adopt this in the future if I'm managing something like a design system again. There were times where we couldn't remember exactly why we made certain decisions or times where we were reliving conversations we'd had before. (That's fine if it's intentional)

To be clear I think this is a good idea but it makes me wonder: a) who is this really for and b) is this potentially the result of an org not trusting designers to do their jobs effectively (whether it's the decisions themselves or justifying them)

Just ask the designer, or look in the documentation. A good designer will have explained their rationale to the client in some document or other. At least that’s what I encourage in my team. Not just for the rationale but also for accountability.

I’ve been trying to introduce Decision Records into our design team (but we are going through a merger rn soooooo … all activity there has stopped). The idea is that each project has a numbered list of the decisions that were made and the rationale.

It’s far from perfect but it helps me a lot to track down separate loose docs if there’s no other way around it. (We don’t really have a separate tool we use for docs and stuff lives in GitHub, confluence and Figma, sometimes also in the clients’ confluence)

it's also good for the inverse, what was a good reason before might not be a good reason anymore. documenting the *why* and not just the *what* sounds valuable.

I've struggled with it for years Sid. I don't think current project management tools do a good job on documenting design decisions. I was even exploring a tool that would improve that, where stakeholders would work on a story with clear ways of documenting design rationale...

This is a really good idea and I wish I’d heard of it 6 years ago

Maybe a way to cross reference neatly is the thing that needs improving... and getting people to actually document... that part of the process needs work too from what I see and hear

I used to keep a doc called “decision log” with my PM. We’d write down key questions and then the date and the decision we came to. Depends on what kind of decisions you’re thinking about though. I don’t usually document the why for smaller decisions

I would also say that if designers are expected to do this kind of thing, I would also expect the same of other EPD roles.. It just seems like it would be unfair otherwise lol

A shared doc sounds transparent! How did you make sure you keeping on top of it? What was the cadence of check in on the doc?

In case you’re not familiar with ADRs, this is an example of what it would look like, roughly: https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md

So in that explicit case (leaving aside the fact that if someone is not in charge they should not be randomly making decisions like that, lol) it felt like we had reasoning for the original decision but this was not 100% documented 🤷🏻‍♀️🤷🏻‍♀️🤷🏻‍♀️

Yeah totally, the context is super important. Also: what was known at the time and what wasn’t! Often new knowledge would have led to different decisions.

If there's a concern about a specific aspect of the design that's usually something I would talk about 1:1 and document outside of Figma. I don't think XFN partners want to know the details about every single detail though (not to the extent of a designer) 

(c)

Have you found any friction with documenting that in Notion? Whats the cadence for adding to it? How do you maintain consistency across teams?

Posts