Hacker News new | ask | show | jobs
by photochemsyn 1342 days ago
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...
1 comments
Kwpolska 1342 days ago
Where do you see the reinvention of UML within ADR? I wouldn't consider ADRs to be that; I'd say ADRs are meant for important decisions with important consequences, not a documentation of every single design choice and every single part of the project, as UML proponents would do.
link
photochemsyn 1342 days ago
Some of the ADR discussions seem to revolve around trying to create a formalized 'use anywhere' ADR model which does looks suspiciously like UML. The general concept (a historical record of the development of the architecture) sounds good, but a one-size-fits-all approach sounds like a bad idea. ADR approachs should probably be heavily customized to fit each project/codebase.

Some people might say, "but if we had standardized ADRs we could efficiently compare different codebases" but that's going back to UML.

link