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

Activity

1. spier

   added

   1-initialDonuts, Early pattern ideas, ... (Please see our contribution handbook for details)Donuts, Early pattern ideas, ... (Please see our contribution handbook for details)

   📖 Type - Content WorkWorking on contents is the main focus of this issue / PRWorking on contents is the main focus of this issue / PR

   on Feb 6, 2025
2. spier

   added this to Patterns Workon Feb 6, 2025
3. spier

   moved this to In Progress in Patterns Workon Feb 6, 2025
4. spier commented on Feb 6, 2025

   

   spier

   on Feb 6, 2025

   MemberAuthor

   More actions

   @tsadler1988 as you wrote the RFC pattern above, I figured this might be interesting for you as well.
5. tsadler1988 commented on Feb 10, 2025

   

   tsadler1988

   on Feb 10, 2025

   Contributor

   More actions

   @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.

   👍React with 👍1Reacted by Peter Rossbach
6. spier

   linked a pull request that will close this issueAdd: initial pattern document architecture decisions #773on Feb 19, 2025
7. spier commented on Feb 19, 2025

   

   spier

   on Feb 19, 2025

   MemberAuthor

   More actions

   @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?
8. spier

   closed this as completedon Feb 19, 2025
9. github-project-automation

   moved this from In Progress to Done in Patterns Workon Feb 19, 2025
10. rossbachp commented on Feb 20, 2025

    

    rossbachp

    on Feb 20, 2025

    Contributor

    More actions

    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?