Hacker News Reader

Comment by jph | Hacker News Reader

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

View on HN

Naturally ADRs are only as good as they are made. That includes the process of coming to a decision and the effort put in writing them precisely and understandably. One can find many templates for them online and then pseudo-fill them, gaining almost zero benefit. Sometimes they are used to merely record premade decisions, which makes them OK for lookup, but adds nothing to the decision making process and is quite obvious when you read them.

The main use of an ADR isn't to arrive at a decision, but to record the choice that was made and why. Filling out an ADR and gaining zero benefit while doing it seems plausible - the hard work of arriving at a certain artefact is already done (hard work isn't a requirement).

In my solely own opinion:

an ADR documents a strategic choice and ties accountability to it's author. The quality of the document (and the content) should work in their own best interest.

Another kind of documentation could be used to record e.g. details of implementation or describing APIs. The latter is focused on building a knowledge base for co-workers, onboarding or end users. edit: I call them REFs.

edit 2: Filling out superfluous forms which ends up of no use to anyone is a waste of time. Cut back on documentation until people starts asking for more of it.

Great resource. Do you teach teams virtually?

Thanks for the link

Reply on news.ycombinator.com