Knewton RFC template

Knewton RFC template on Google Docs

This template is intended to help solicit feedback on proposals and designs. It presents an outline to help organize your ideas, and provides guidelines and examples of what should go in each section. The outline should be considered a starting point and not a strict format that must be followed. Guidance on the RFC process can be found here.

Foreword

Identify your audience before you start writing. These are the people who are impacted by what you’re proposing, subject matter experts, or people who can make the proposal happen/not happen. It may be Product, a particular team, tech-at-large, or some other group. Address that audience at the beginning of your doc.

In one sentence, summarize what’s being proposed. Then briefly describe how the document will make a case for the proposal. This section should be no more than a couple sentences.

Motivation

Why is this change being proposed? You first need to state the problem and make a case that the problem is worth solving.

  • Focus on the impact of the problem – monetary expense, wasted time, unnecessary risk, customer unhappiness, etc.
  • Quantify the impact. Metrics are great, estimates are ok too.
  • State the immediate cause of the problem. Some potential causes could be scaling issues, missing functionality, or broken process.
  • Use terminology that’s relevant to your audience.

Don’t write too much. This section should be less than one page – one or two paragraphs or a couple bullet points. Do not go in depth about the cause of the problem. If the problem is unhappy customers because of scaling-induced slowness, it’s ok to simply say “because of scaling issues”.

Don’t describe your solution in this section. It’s ok to allude to a better way or suggest we could achieve a net-positive gain by fixing the problem, but don’t spend more than one or two sentences talking about solutions. You’ll go into more detail later.

Background

The purpose of this section is to provide context for the reader to understand what you’re proposing. Describe the current state of the world to illustrate the scope and nature of the problem – go into detail about the immediate causes mentioned in the Motivation section. Some things to talk about could be data schemas, access patterns, race conditions, unnecessary dependencies, or duplicated logic (this is not an exhaustive list).

People are lazy and don’t read, so you’ll need to prioritize information. Don’t bury important details alongside less important information. Pictures are good too.

The level of detail in the section is highly dependent on your target audience and the issues you’re describing. If the motivation is missing functionality, you might skip this section entirely. When in doubt err on the side of being too concise and put deeper background info in the appendix.

Requirements

AKA success criteria. Briefly (one or two sentences) state your solution, and then talk about all the good stuff stakeholders will get once the proposal is implemented – impact of the solution. This section is a counterpart to the Motivation section and the same guidelines apply.

Don’t go in-depth on your solution in this section – you want to present goals and implementation separately.

The requirements should make it very clear when the your goal has been achieved.

Bad: “We’ll make the /do-something endpoint much faster”
Good: “We’ll achieve a < 100ms response time (99th) for the /do-something endpoint”

Talk about the things your proposal won’t do. This will prevent scope creep.

Implementation

Describe scope and nature of your solution. Start by describing the final state of the world once your proposal has been implemented. Focus on things that are difficult to change – typically public interfaces, data schemas, frameworks/other tech choices, or human processes. (Humans are notoriously difficult to refactor.)

Again, people are lazy and don’t read, so prioritize information and use pictures when possible. If you are proposing a new schema, provide a schema diagram that highlights the changes. If you’re proposing a new interface, provide the method signature or REST documentation.

Then explain step-by-step how you’ll get from the current state to the final state. This is sometimes broken out into a separate section titled “Migration Plan”. Call out dependencies and teams or services that will be impacted. Readers should get a rough sense of how much work is involved, or the cost of the solution.

Avoid introducing ideas that aren’t directly related to the problem you’re solving – at best they will invite bikeshedding that distracts from the important issues, at worst they will cause an otherwise good proposal to stall. Make use of existing conventions where possible.

Be opinionated! Don’t propose multiple solutions and ask commenters to pick one. The best way to solicit opinions is to make a statement (whether you’re confident in it or not) and wait for people to tell you you’re wrong. If you considered other solutions, note that and put details about alternate solutions in the appendix.

Signoff & Comments

Prefill the names of anyone whose signoff is required.

Appendix

This is where you put supporting information that might be relevant some readers but not all. Alternative but rejected implementations and dissenting opinions should also go here.

Check out the Knewton RFC template on Google Docs for examples and better formatting.