Fork me on GitHub
#architecture
<
2017-01-04
>
gdeer8116:01:04

@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?

mtnygard16:01:33

@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.

mtnygard16:01:17

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.

gdeer8116:01:44

oh wow, they even documented the decision to use ADRs

gdeer8116:01:17

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

gdeer8116:01:08

@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

lmergen17:01:54

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 ?

fellshard17:01:29

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

gdeer8119:01:47

@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

lmergen19:01:01

that seems like a good idea, yes

lmergen19:01:07

i think i might introduce this

fellshard19:01:40

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.

jstokes19:01:40

git submodules