log4brains
log4brains copied to clipboard
thomvaill
Rename `docs/adr` default directory to `docs/decisions` to improve usage
Feature Request
Feature Suggestion
For now, the default directory for ADRs is docs/adr, because it was commonly documented like this:
- https://adr.github.io/madr/
- https://github.com/joelparkerhenderson/architecture_decision_record
But @joelparkerhenderson recently gave me this interesting feedback:
Some teams much prefer the name "decisions" over the abbreviation "ADRs". When some teams use the directory name "decisions", then it's as if a light bulb turns on, and the team starts putting more information inton the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds of information can use the same template. We hypothesize that people learn faster with words ("decisions") over abbreviations ("ADRs"), and people are more motivated to write work-in-progress docs when the word "record" is removed, and also some developers and some managers dislike the word "architecture".
So I propose to change the default value in Log4brains, because I am convinced that ADRs should not be reserved only for important architectural decisions. They are also beneficial for all kind of decisions, and we should promote that.
Possible Implementation
- Search and replace all occurrences of
docs/adrin the README - Search and replace all occurrences of
docs/adrin the code, only when it is used as a default value - Create an ADR for this :-)
What's the status of this?
I personally think that "decisions" is more immediately understandable than "adr".
I agree too. I'll make the change in the next version. Or if someone wants to contribute, PRs are welcome :-)
I just tried implementing this, there are over 2200 mentions of ADR in the repo, some of them are non-obvious to replace, for the time being I renamed my folder and changed the adrFolder as the project is configurable.
One minor but eventually "bike sheddable" discussion is singular vs plural, the project is consistent right now with all singular, by having docs/decisions and log4brains decision new, thing could get confusing, maybe a command alias would be welcomed in this case.
I've taken a stab at updating this in #98. Please feel free to provide feedback.
