Agreed, it requires leadership and cultural buy-in from others.
you are probably already writing ADRS. Often times a story/ticket has description field with all the information that goes into an ADR. Just a matter the engineers working on that story to copy/pasting--put into their own words for an ADR.
Which then solves several pieces. First, anyone reviewing that code now knows exactly what we are trying to solve. Because if an engineer from reading a story/ticket that was groomed and placed into a sprint is unable to re-frame the work as an ADR... then something is wrong and I doubt the final deliverable will satisfy the acceptance-criteria.
Also, when you leave JIRA for a new ticket/system, all that information is lost. So having the ADR live within the CodeBase prevents silo.
Cockroach Labs, uses the RFC concept but similar to ADR.
But you're right, it does come down to leadership, and I've been at organizations where trying to change cultural-process is a massive challenge.
I totally agree, and I saw some success myself by introducing ADRs as a collaborative decision process instead of a documentation methodology.
Because documentation "is for the future", whereas using ADRs in pull requests to take decisions is "for the present". It's a lot easier to sell a methodology that is useful now, instead of being possibly useful in the future ;)
And also, I am trying to create a nice tooling for ADRs, especially to be able to communicate on them, with my new open-source project: 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!
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.
Agreed, it requires leadership and cultural buy-in from others.
you are probably already writing ADRS. Often times a story/ticket has
descriptionfield with all the information that goes into an ADR. Just a matter the engineers working on that story to copy/pasting--put into their own words for an ADR.Which then solves several pieces. First, anyone reviewing that code now knows exactly what we are trying to solve. Because if an engineer from reading a story/ticket that was groomed and placed into a sprint is unable to re-frame the work as an ADR... then something is wrong and I doubt the final deliverable will satisfy the acceptance-criteria.
Also, when you leave JIRA for a new ticket/system, all that information is lost. So having the ADR live within the CodeBase prevents silo.
Cockroach Labs, uses the RFC concept but similar to ADR.
But you're right, it does come down to leadership, and I've been at organizations where trying to change cultural-process is a massive challenge.
I totally agree, and I saw some success myself by introducing ADRs as a collaborative decision process instead of a documentation methodology.
Because documentation "is for the future", whereas using ADRs in pull requests to take decisions is "for the present". It's a lot easier to sell a methodology that is useful now, instead of being possibly useful in the future ;)
And also, I am trying to create a nice tooling for ADRs, especially to be able to communicate on them, with my new open-source project: 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!