Skip to content

Documenting design decisions

RFC

Request for comments (RFC) is a type of document which describes the design decisions, architecture, or important decisions about a system.

First of all, you need to collect all the information you want to propose to solve the problem. After that, you need to write a document which describes the problem, the solution, and the reasoning behind it.

And the main last step is a discussion. Team members need to review the document and mark the inconsistencies, ask questions, and propose another solution.

To conclude, preparing, writing, and sharing RFCs with your team to review and iterate over the thought process that went into the proposal is an easy way to structure the R&D process.

ADR

Now that we've explored the steps from research over discussion up to deciding whether to adopt a proposal or not, we're entering the domain of Architecture Decision Records (ADR).

ADR is a document that captures the important architectural decisions made along with its context and consequences.

In other words, ADR it's short and core version of RFC with accepted solution.

Resources