Clojurians Log v2

@mtnygard I saw your blog post on ADRs from 2011 (http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions), is there anything that you would add to that 5 years later?

@gdeer81 I think it holds up pretty well. I'd add the Arachne project as a good open-source use of ADRs so there are some nice examples. Maybe also say that "alternatives considered" typically below in the context. If you considered a solution, but rejected it there must be some evidence or reasons & that's part of context.

Really one of the hardest parts to write is the context. That's because you have to make a bunch of implicit knowledge explicit so people can understand your decision in the future.

oh wow, they even documented the decision to use ADRs

we've been so hung up on trying to document things in confluence and sharepoint that we never thought to just use git

@mtnygard you've worked with ATG before, so you know the butterfly effect it can have when you make a decision in a framework that complex

the problem with git (at least for us) is that architecture decisions usually involve multiple repositories. is there any way around that, other than creating a repo just for architecture decisions ?

Depends on the scale/scope of the decision, yes?

@lmergen yeah I was thinking about that same thing with our Tibco integrations that are just little machines connected together but each one is kept in a separate repo so modifying how pricing changes flow from the source system, to all the stores, and the website requires touching like 5 or 6 repos. I guess we could reference ADRs in other repos to show the relationship. Creating a separate repo just for documentation seems kind of awkward

that seems like a good idea, yes

i think i might introduce this

Isn't there a feature of Git that allows sub-repositories? You could create a repository that 'points' to these other repos and documents their integration / common architectural decisions appropriately.

git submodules