search

thomvaill / log4brains

✍️ Log and publish your architecture decisions (ADR)
Apache License 2.0
1.12k stars 94 forks source link

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

Open thomvaill opened 3 years ago

thomvaill commented 3 years ago

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

fire commented 3 years ago

What's the status of this?

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

thomvaill commented 3 years ago

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

fire commented 3 years ago

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

cabello commented 3 years ago

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.

tylerhubert commented 1 year ago

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

joelparkerhenderson commented 1 year ago

@tylerhubert Looks great!