How to Write Requests for Comments (RFCs) and Architecture Decision Reviews (ADRs)

It’s three letter acronym (TLA) time!

Everyone loves documentation!

Audience

This article is aimed at Software Engineers looking to document the decisions they make day-to-day. It will focus first on how to write up an idea so that others can offer opinions (requests for comments). We then move to a complementary concept, architecture decision records, which communicate architectural strategies.

It is important to note that not only are these useful documentation techniques, they help push planning forward. By writing up and critiquing our decisions before we implement them, we rapidly identify errors, saving time and money.

We are going to assume you have a reasonable amount of developer experience, and a basic grounding in how engineering teams function.

Argument

This article is split into two halves, one for each documentation type.

RFCs

An RFC is used as a light-touch technical design. When we approach a non-trivial problem we use RFCs to write down our thoughts. This opens ideas up to a wider audience to discuss tradeoffs and implications of any decisions.

Using these documents exposes plans to those internal and external to our team, minimises risk, creates lasting records and make reaching agreements asynchronous.

Note, the purpose of these documents is to put everyone on the same track going forward. It’s not to completely plan every facet of the work.

An example of when we may use them could be applying alarms to one of our systems. These alarms would alert us when something goes awry. We raise an RFC to ask for advice on what we should alarm on, and which thresholds we should use.

So what do they look like?

We suggest the following sections:

• Executive Summary: This includes context and motivation.
• Scope: An explicit list of what is in and out of scope.
• Participants: All participants in the RFC. This can be product owners, developers, architects. Whoever has a stake in the decision.
• Status: My personal recommendation is to maintain a table of two columns. The first column is the list of statuses (for example: started, in review, approved, superseded), the second column is then the date that the status began. This tabular method allows for a fuller history.
• Proposal: What you would like to receive comments on. The fuller this is the less questions you will have. Remember, this will be referred to in the future, so include details that will be less obvious in the coming years.
• Pros/ Cons: A concise, itemised summary of the good and bad points.
• Alternatives: Any potential alternatives to your proposal.
• Remaining Questions: Anything you are still unsure of. Commenters may be able to help clarify.
• Conclusion: A terse statement summarising the above.

An RFC can then be expected to go through the following stages.

1. Writing and submitting: Some time will be required to write your RFC, after which you will need to present it to your stakeholders. A popular option could be to publish it to a relevant Slack/ Teams channel, or send it via email. You may need to chase it up!
2. Comments: Hopefully, you will now receive some comments! The medium you have used to write your RFC will be very important here, remember it will need some commenting facility. As the writer of the RFC it will be your responsibility to time box and moderate discussions. Remind others that it is an opportunity for them to offer their point of view, not to fight for a certain solution.
3. Concluding: At this point draw the conversation to a close. All questions do not need to be resolved, but everyone must be on the same lines.

Our final suggestion is to just give it a try! All recommendations are only jumping off points. Try it out and adapt it for whatever works best for your team.

ADRs

By this juncture hopefully we have understood that Architecture Decision Records are simply a way to document a choice we have made regarding our system design. We use them to share information with stakeholders and developers, both present and future.

It is really important to properly factor them into your development process. I personally use them as an outcome of spike tickets. Each time we need to do some investigation we raise a spike, and the outcome of the spike is written up into an ADR.

These documents can be stored anywhere but must be easy to access and refer to. Some teams store them in their version control system, however this is harder to access for non-technical people. Confluence or similar may be preferable.

To fully understand ADRs we need to define some extra terms:

• Architecturally Significant Requirements (ASR): This is the change that demands an alteration to our system architecture. An example might be we need to have our application send emails to users.
• Architecture Decision (AD): The decision you make on how to address your ASR. In our example we may have decided to use a cloud-managed email service rather than our own SMTP server.
• Architecture Decision Record (ADR): How you document this decision.
• Architecture Decision Log (ADL): The collection of ADRs representing the rationale behind all choices in the application design.

With these terms in place, let’s think about what we would like to include in our document. We are going to take the structure from Micheal Nygard, although other options are available.

The reason we choose this particular format is that it is lightweight. From my experience of developers, they dislike writing documentation. The more straightforward it is to do, the more likely it is they’ll do it.

There are five sections:

Title

A good format for the title is ADR-nnnn dd/mm/yyyy description. The nnnn component represents an increasing number beginning from 1. For example, ADR-0002 29/07/2022 Adding Email Functionality.

Status

The status of the ADR. This can mimic the RFC format.

Context

In order to make a decision we first need to know all of the influencing factors. In this section we want to detail our current situation in as much detail as possible. Remember, developers in the future will look back on this document and won’t have the insights you have now.

Things to touch on include:

1. The motivation behind the proposed change (for example, why are we sending emails).
2. All of the other work going on (for example, we’re also working on this other huge chunk of functionality).
3. Inhibiting factors. A lot of systems have an ‘ideally we’d do it this way, but in 1981 someone did this, which means we can’t’ issue. Make this explicit
4. The state of the team. Perhaps you have a lot of more junior members which will cause one particular route to be more challenging.

Decision

Describe the process of making your decision. This should include all of your investigations up until reaching your final choice. For example, you may have considered a number of options and experimented with each until you found the one you wanted.

By documenting this you don’t lose the work you put in! Perhaps the other options didn’t work this time, but could be useful later on.

Remember, experiment and prove your chosen route. There can be a tendency to come into a decision with your mind already made up. This can guide you, but don’t let it exclude other potential options.

Consequences

Here we describe the outcome of the decision, both positive and negative. This will include:

• Effects: What the ramifications of our decision are.
• Outputs: What will be created as part of the ADR. This can include other ADRs. Answering some questions often raises others!
• Follow Ups: Anything we need to follow up on.
• ADR Reviews: We may want to set a date to come back and review our decision making process after we carry out the work.

Note, all outcomes should have proper tickets created along with them in order to track the work.

There is also the concept of A Definition of Done for Architectural Decision Making. You can use these checks to make sure your ADR is indeed finished.

Conclusion

In conclusion, we have discussed two complementary ways of documenting our design decisions.