So awhile back we decided to write ADRs and add them to the repo. I realized we haven't really done anything since we added the first one. I am thinking maybe we could remove the adr folder and instead create an "Important Conversations" category in our readme and link to issues or PRs that we tend to have meaningful conversations. I'm not sure how much this would be used, but seems easier and that we would be more likely to link those convos rather than having to write up new ADRs.
Thoughts?
bryceosterhaus
All 5 comments
I think we can still keep ADRs, I don't think we're using them yet because I think we're thinking of them as very well written and an article narrative that keep us from creating new ones, I think we have a lot of content that can become ADRs. I like the idea of linking PRs and issues but I think they don't replace the idea of ADRs, issues and PRs can have very fragmented and somewhat scattered information. I think we can create more summarized ADRs. The idea is that they need to contain relevant information just about the decision and we can link them to issues and PRs.
We can follow with more descriptive and some well-summarized ADRs on the subject by adding the link to issues and PRs.
What do you think?
matuzalemsteles
on 9 Dec 2019
I think my main concern is that there is a lot of overhead in writing and ADR, and its been easy to not write them since they take a lot of effort. Maybe we could compromise and make ADRs a bit more flexible and useful. We could start each one by a simple md file with a link to an issue and then it might incentivize us to expand on it more or summarize the issue. This way its a really low barrier of entry. Ideally we want something helpful, and low barrier of entry.
bryceosterhaus
on 9 Dec 2019
Sounds good to me!
matuzalemsteles
on 9 Dec 2019
Hey @bryceosterhaus, @matuzalemsteles!
I'd say time has proven we're not ready for ADRs at least the way we envisioned them... and that should be totally fine. My advice would be not to try too hard to keep it. If something isn't working, it's often better to try something else... maybe in time we will get back to this original idea, but we can't force it.
I'd encourage you to find something that's useful and is probably less structured to begin with. For one, Wiki is enabled here, so it might be a good thing to start recording thoughts, technical ideas or architecture information in there (just a thought).
jbalsas
on 18 Dec 2019
moved to wiki
bryceosterhaus
on 19 Dec 2019
Related issues
dgarciasarai
·
4Comments
bicienzu
·
3Comments
dgarciasarai
·
3Comments
drakonux
·
4Comments
hold-shift
·
3Comments
Most helpful comment
Hey @bryceosterhaus, @matuzalemsteles!
I'd say time has proven we're not ready for ADRs at least the way we envisioned them... and that should be totally fine. My advice would be not to try too hard to keep it. If something isn't working, it's often better to try something else... maybe in time we will get back to this original idea, but we can't force it.
I'd encourage you to find something that's useful and is probably less structured to begin with. For one, Wiki is enabled here, so it might be a good thing to start recording thoughts, technical ideas or architecture information in there (just a thought).