Giters

thomvaill / log4brains

✍️ Log and publish your architecture decisions (ADR)

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Rename `docs/adr` default directory to `docs/decisions` to improve usage

thomvaill opened this issue · comments

commented

Feature Request

Feature Suggestion

For now, the default directory for ADRs is docs/adr, because it was commonly documented like this:

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/adr in the README
  • Search and replace all occurrences of docs/adr in the code, only when it is used as a default value
  • Create an ADR for this :-)
commented

What's the status of this?

I personally think that "decisions" is more immediately understandable than "adr".

commented

I agree too.
I'll make the change in the next version.
Or if someone wants to contribute, PRs are welcome :-)

commented

Should log4brains adr new have an alias for log4brains decision new?

commented

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.

commented

I've taken a stab at updating this in #98. Please feel free to provide feedback.