[Pattern Draft] Document Architecture System Decisions and the Technical Depts

[spier]

Let's help @rossbachp to get this pattern draft integrated into our repo:
https://github.com/rossbachp/DeciCollab/blob/main/Document-Architecture-Decisions-Pattern.md

It may be related to one of our existing patterns:
https://patterns.innersourcecommons.org/p/transparent-cross-team-decision-making-using-rfcs

Also the repo https://github.com/rossbachp/DeciCollab contains a lot more context about the pattern idea. Well worth the read, and contains a lot of further reading about the topic!

Will try to setup an initial call to help the pattern authors and understand where they are headed with this pattern.

Certainly an amazing draft that they have there already!

[spier]

@tsadler1988 as you wrote the RFC pattern above, I figured this might be interesting for you as well.

[tsadler1988]

@spier absolutely, we use ADRs alongside RFCs so can add another known instance.

There was some interesting discussion on the RFC pattern about ADRs - there's a lot of crossover, and for some companies they are one and the same.

[spier]

@tsadler1988 pattern is already available in our repo now:
https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/document-architecture-decisions.md

Curious to hear what you think.

And yes, the point of "for some companies they are one and the same" will be interesting for us here as well. How do we treat the situation where we have two rather similar patterns?

• Publish both
• Try to make each pattern more distinct/different from one another
• Merge the two
• other options?

[rossbachp]

The commonality between RFCs, ADRs, and TDRs lies in their structured approach to documenting decisions, exploring different options, and fostering discussion before finalizing and publishing the outcome.

• RFCs (Request for Comments) are typically used to propose standards, often requiring months or even years to reach a consensus. They facilitate broad, community-driven discussions that shape widely accepted norms and protocols.
• ADRs (Architecture Decision Records) are frequently used within teams to document local decisions. They provide concrete justifications for implementations, procedures, or methods that are immediately applied. Over time, these localized decisions can evolve into standards for a project or even an entire organization.
• TDRs (Technical Debt Records) serve to document and track technical debt and associated risks. By maintaining visibility on these issues, teams can strategically manage and address them.

Both ADRs and TDRs are often subject to regular reviews and are deliberately adapted based on new insights gained during implementation and usage.

This perspective highlights the complementary roles of RFCs, ADRs, and TDRs in decision-making and knowledge sharing within organizations. Would it make sense to incorporate this explanation to clarify the purpose and interplay of these formats in the documentation?