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

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.

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.

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

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.

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

Conclusion

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

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
James Collerton

James Collerton

Senior Software Engineer at Spotify, Ex-Principal Software Engineer at the BBC