Skip to content

2023 01 16 ADRs & RFCs differences and process

technicalWritting softwareArchitecture systemsDocumentation

Need

At work I am currently designing a new system together with my team. The system will start as an MVP, and in will be extended in features and scaled to users and regions over time.

With such scale of the system, the people working on the system will also scale, therefore the need to start with a lean documentation approach, something that is the minimum required for us to kick start, and iterate over it, adding the necessary layers.

Types of documentation

  1. Product documentation: Anything related to UI/UX design, functionality, users, business needs, and any other similar input that characterises the system
  2. Technical documentation: Systems documentation including architecture (structure), best practices, non functional requirements. This documentation aims to describe the mechanics of how the system works. Within this type there are some subtypes I can identify:
    1. Non Functional requirements/-ilities, and how we measure them
    2. Systems/Architecture diagrams/C4Model
    3. RFCs/ADRs
    4. Practices etc

When to do an RFC and when to do an ADR?

For that, let's look at this definition of software architecture

“In most successful software projects, the expert developers working on that project have a shared understanding of the system design. This shared understanding is called ‘architecture.’ This understanding includes how the system is divided into components and how the components interact through interfaces. These components are usually composed of smaller components, but the architecture only includes the components and interfaces that are understood by all the developers.”

Martin Fowler in Who needs an architect

Here we can get the point that suggest: * Architecture is about the overall structure of the whole system, meaning Architecture > Design * Architecture is a social construct because it depends on group consensus as well as on software.

So, within this context, and RFC is suitable to design decisions, and ADRS for architecture decisions.

ADRs

Alternative

When to make an ADR

Martin Fowler described an Architectural Decision (AD) as “a decision that you wish you could get right early” in an IEEE Software article.

Translation: when the decision is architecturally significant.
Architectural significance 1. Architectural decisions directly or indirectly determine the non-functional characteristics (or qualities) of a system (think -ilities) 2. Each decision describes a concrete, architecturally significant design issue (problem) for which several potential solution options exist and provides rationale for the decision outcome (the selection of the chosen solution option, that is), for instance by arguing whether and how the desired quality attributes will be achieved. 3. Architectural decisions concern a software system as a whole, or one or more of the core components of such system (whatever the “core” might be).

Architectural significance test
Do this to decide if making an ADR makes sense for this use case 1. Impact on business value and risk? 2. Key stakeholder concern? 3. Unusual quality-of-service requirement (at least one order of magnitude more advanced than previous ones)? 4. About external dependencies that are uncontrollable, unpredictable or unreliable? 5. Cross-cutting, system-wide impact? 6. First-of-a-kind character (novelty for team)? 7. Caused bad experience and trouble in the past?

Source

Process to make an ADR


flowchart TB
  A[Seek Evidence proposed solution works] <--> B[Establish selection Criteria and alternative]
  A & B --> C[Seek Agreement]
  C --> D[Document decision outcome]
  D --> E[Realization and plan a Revision in the future]

Source

Process checklist

  • Are we confident enough that this design will work (Evidence)?
  • [] Have we decided between at least two options, and compared them (semi-)systematically (Criteria) ?
  • [] Have we discussed among each other and with peers just enough and come to a common view (Agreement)?
  • [] Have we captured the decision outcome and shared the decision record (Document)?
  • [] Do we know when to realize, review and possibly revise this decision (Realization & Revise)

Suggested template
Decision record template by Michael Nygard

RFC

When to make an RFC

  • You want to frame a problem and propose a solution.
  • You want thoughtful feedback from team members on our globally-distributed remote team.
  • You want to surface an idea, tension, or feedback.
  • You want to define a project or design brief to drive project collaboration.
  • You need to surface and communicate around an important, highly cross-functional decision.
When to skip the RFC
  • You want to discuss personal or sensitive topics one-on-one with another team member.
  • If you can decide on your own. In the vast majority of cases, creating an RFC to explain yourself will be overkill. RFCs should only be used if a decision explicitly requires one of the bullets in the section above.

Process

Suggested process

  • Draft the proposal for the type of problem, feedback, practice, that you want to propose. Create spike if necessary
  • Seek for comments and place a due date for the comments
  • Bring topic to architecture forum, web guild or so, if necessary
  • Plan and do implementation

Open decision:
Confluence? or Git?

TR Template

## Summary
### Goals
### Non Goals
## Overview
## Product requirements
# Detailed design
# Risks and unresolved questions
Other alternatives

-   Background
-   Proposal
-   Abandoned ideas
-   (Custom sections, for example:)
-   Implementation
-   UX
-   UI

Notations to consider

Status

Draft | Proposed | Published

Type

Experimental | Informational | Best Current Practice | Required

Scope

The scope of work affected by the RFC document.

Notational conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119, RFC8174 when, and only when, they appear in all capitals, as shown here, and without quotes.

Context

A description of the problem space and/or requirements that this RFC is set to address.

Decision

A description of the proposed solution, which sets out the specifications of the implementation of the RFC. Should include specific details on how the solution addresses the requirements as laid out in the Context section.

Consequences

Any consequences that are in play as a result of the decision being put into place.

References

Technical decisions that scale the org

RFCS

Further reading