Nice article! I really liked that you mentioned that a decision does not have to be "perfect" to be logged.
I think this is not emphasized enough in the articles we usually read on ADRs.
And it's even more true when you make a decision for "non-catholic" reasons, like "we were in a hurry" or "we don't have a resource that is experienced in that tech": you should definitely log this context because this is a piece of precious information for the future.
Regarding tooling, I also like the simplicity of Markdown, but with experience, I saw the teams I worked with struggling with communication on ADRs: they were not read, difficult to browse the "history" of the project quickly, to differentiate active vs outdated ADRs...
That's why I open-sourced Log4brains: github.com/thomvaill/log4brains
This is a CLI + web UI that lets you manage and publish your ADRs from Markdown to a static website, with search, flow graph and other useful features.
This is a beta, so your feedback is very welcome!
Thanks for taking time to read the post. Documentation in our industry is seen as a bit of waste which is a shame really. Documenting key design choices should never be considered a waste, because it affords you the opportunity to reflect and learn. Simply invaluable!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Hi,
Nice article! I really liked that you mentioned that a decision does not have to be "perfect" to be logged.
I think this is not emphasized enough in the articles we usually read on ADRs.
And it's even more true when you make a decision for "non-catholic" reasons, like "we were in a hurry" or "we don't have a resource that is experienced in that tech": you should definitely log this context because this is a piece of precious information for the future.
Regarding tooling, I also like the simplicity of Markdown, but with experience, I saw the teams I worked with struggling with communication on ADRs: they were not read, difficult to browse the "history" of the project quickly, to differentiate active vs outdated ADRs...
That's why I open-sourced Log4brains: github.com/thomvaill/log4brains
This is a CLI + web UI that lets you manage and publish your ADRs from Markdown to a static website, with search, flow graph and other useful features.
This is a beta, so your feedback is very welcome!
Thanks for taking time to read the post. Documentation in our industry is seen as a bit of waste which is a shame really. Documenting key design choices should never be considered a waste, because it affords you the opportunity to reflect and learn. Simply invaluable!