Architecture diagrams enable better conversations

Re:Architecture diagrams enable better conversations by politician on Tuesday August 22, 2023 @11:06AM (#37223833)

One of the areas I would like to see addressed in guidance for drafting both architecture diagrams and specifications is in the documentation of the basis for design decisions. Which risks catalyzed a particular design or approach on a particular feature and to what degree?

In my own work, when I need to revisit a spec months afterwards, I often have trouble because I've forgotten parts of the context that I had at the time the spec was drafted. The situation is a bit like the Chesterton's Fence where the original person that set the fence in the middle of the road has also partially forgotten why it needs to be there. It was so obvious at the time...

Do others supplement their architecture diagrams and specifications with a cross-refenced list of risks, alternatives, and probabilities?

[ Parent | on HN ]

Re:Architecture diagrams enable better conversations by kzhen on Tuesday August 22, 2023 @11:25AM (#37224073)

Hi, article author here, we supplement our architecture diagrams with Architectural Decision Records (ADRs) https://github.com/joelparkerhenderson/architecture-decision... in the ADR we capture: - options considered - pros/cons of different options - chosen option - who was involved in making the decision

there are a few other fields like component, product etc these are very useful for capturing decisions and something I should have mentioned in the article.

[ Parent | on HN ]