Extended Template

[koppor]

Coming from the discussion of status at #2 and seeing https://stackoverflow.com/a/7115411/873282, we should think of template-lean.md and template-full.md.

Zimmermann et al. compared other templates at https://www.ifs.hsr.ch/fileadmin/user_upload/customers/ifs.hsr.ch/Home/projekte/ADMentor-WICSA2015ubmissionv11nc.pdf:

[pixelbrackets]

Offering two different formats increases:

• maintenance effort (add features to two files, two examples in README, two github-pages renderings etc.)
• information density for new users (“why are there two formats?, whats the difference? which fits my use case?“)

Since most of the fields are optional any integrator may decide on his / her own how the template should look like. It should be recommended instead to edit the template.md to your use case and remove any optional fields you dont want to use in your company. The original MADR template is still linked in the index.md, so this is no drawback.

[koppor]

For me template-lean.md would be a shortened template-full.md. OK, maybe, we should call that "profiles". But then, it gets complicated... information density: "Why profiles? Which profile should I use?"

Maybe the aspects "Risks and Issues", "Assumptions and Constraints", "Points of Note" can just be put as text in MADR to inspire the writer. I am not sure how much these keywords help. Maybe, MADR is good enough in its current state.

[koppor]

Extended template by @FaKeller: https://gist.github.com/FaKeller/2f9c63b6e1d436abb7358b68bf396f57

[FaKleiser]

Hi @koppor, thanks for the mention! I fully support the idea of having various templates with different verbosity. To me, an ADR needs to be pragmatic.

Documentation is usually difficult to maintain (or even create) for a lot of dev teams, and ADRs are a really expensive form of documentation (takes long to research, write and find a conclusion). On the upside however, ADRs can have a massive impact on functional and non-functional requirements and are definitely worth the time. Convincing people to regularly identify when to create an ADR in the first place, and then writing that down, along with probably some more research is probably key. Having a short/medium/extended template could potentially help there.

Next to that, I would also consider the application domain as a key factor in choosing a template. When writing a simple mobile app, architecture might not be as important, but an ADR here and there may still be helpful. When building a solid backend (with DDD, event sourcing, or the like) for an average domain that should last a couple of years, it may be more worth to invest in ADRs. Now if a team is coding the engine control unit of a car, a spaceship control, or a complex drug dosage application I deeply wish they were sincerely using ADRs for important decisions (next to other good safety practices, of course).

TL;DR: lets create and promote some templates of different granularity/verbosity tailored to different use cases. People will then also more likely start using them.

[koppor]

TL;DR: lets create and promote some templates of different granularity/verbosity tailored to different use cases. People will then also more likely start using them.

Maybe, you could convert your template to a full repository to enable issues? If that is too much work, just add it as is to https://github.com/joelparkerhenderson/architecture_decision_record :)

Meanwhile, I will create an ultimate comparison of ADR templates. We can join forces, if you want.

[schubmat]

@koppor Back last year, when I introduced DecisionCapture with its multiple templates (three in Markdown and one in Excel) we offered it to students in that tiny study to make them use it. Later, you came up with MADR containing only one template. They considered this to be leaner than my approach (see their rationale)

I know, this is far from representative. But I'd even bring up some more arguments for one template than multiple ones. I just had a look again at the usage of your template over time by the aforementioned students (see here) and I noticed that they kept changing the template again and again slightly. In other words, the template has not been used in a consistent way. Although the desired information is in there, IMHO these captured decisions contradict the provisioning multiple templates. I would undermine this problem with further examples of the other studies I conducted with students during my research, but they are not yet published.

TL;DR: I think if you are not an enthusiast, multiple templates will cause inconsistent usage and inconsistently documented ADRs. Saying so, I'd promote the idea of a single template per project using MADR. This will keep things plain and simple. For those who want more, you could come up with extensions to adr-tools which would initialize the template according to the parameters provided.

To finally mess up things, personally, I also would envision to have multiple templates for differing scenarios. However, this requires aware usage of those.

Let's hope my few thoughts didn't confuse too much ;)

[koppor]

Quick thought: By adding more guidance (READMEE, examples), this should be doable.

[koppor]

We should be careful not to create a full-blown template which no one fills out.

Here a screenshot of the IBM UMF table (also contained in the table above)

[source]

[koppor]

Current MADR seems to be flexible enough. I will reopen if there are more wishes, ideas, experience reports, ...