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.
If anyone wants to see Polar in action on a GitHub issue, I'm experimenting with Polar on my Architecture Decision Record repo:
https://github.com/joelparkerhenderson/architecture-decision...
(I'm on the fence about the value of Polar for this kind of issue... see what you think)
Sounds like an architecture decision record. Here's an example ADR template: https://github.com/joelparkerhenderson/architecture-decision....
Architecture Decision Records can help teamwork. I teach tech teams about these, and maintain a repo of templates and examples:
https://github.com/joelparkerhenderson/architecture-decision...
The article mentions Architectural Design Records (ADR) which can be included as a folder in the git repo for the project, as a means of documenting the historical decisions that led to the project's current structure. Some of that seems overly complex or formalized (i.e. reinventing UML and all the problems that came with it), but having that history in some kind of constant format would likely help overcome any novelty issues and help people grasp what's going on. The simplest format discussed seems the best for most cases:
https://github.com/joelparkerhenderson/architecture-decision...
I was actually looking for good alternatives today and came across a few good resources:
* https://microsoft.github.io/code-with-engineering-playbook/d...
* https://github.com/joelparkerhenderson/architecture-decision...