search

microsoft / code-with-engineering-playbook

This is the playbook for "code-with" customer or partner engagements
https://microsoft.github.io/code-with-engineering-playbook/
Creative Commons Attribution 4.0 International
2.15k stars 568 forks source link

Improve Discoverability of ADRs: Reference more ADR documentation #945

Open zmmille2 opened 1 year ago

zmmille2 commented 1 year ago

Is your feature request related to a problem? Please describe. During some recent conversations with coworkers, ADRs were mentioned as a practice that plenty of crews use, but that they weren't sure whether this content was in the playbook.

It is, but the fact they didn't know means that we could probably do more to make this content more visible.

Describe the solution you'd like I think the ADR section should get more attention at lower (and more) levels of the playbook. I'd like to add text recommending them wherever there is guidance around making technical decisions, especially in the documentation section.

Furthermore, during these discussions, there were some useful references:

The first seems like a great addition, the latter two could also be useful.

Describe alternatives you've considered If we don't adopt this change, people will remain unaware of ADRs in the playbook. It's possible this will improve visibility of ADRs.

Additional context N/A

TessFerrandez commented 1 year ago

just going through old issues and noticed this @zmmille2 is this something you want to PR or do you want someone else to add this, I'm happy to do it if you wont