I’m a big fan of writing things down. Proposals, Documentation, Notes, etc.

Proposals have many benifits:

• They force you to get the ideas in your head out into the world. That in itself forces you to think about those ideas in depth and helps you understand them better.
• They allow multiple people collaborate on the idea before any code gets written. It’s a good way to get buy-in from others.
• They limit surprises. When the work the proposal proposes is done, no one would be surprised that it happend. Consensus isn’t the goal, and every proposal must have a clear decision criteria and a decider. That said, everyone must have voiced their opinions and eveyone must know the conclusion.
• They create a paper trail for why certain design decisions were taken.
• They allow higher-ups to give their input and understand what business value the team is creating.
• They also allow you to write more, which is a skill that is so important to develop.

The rest of this blog post is a template I’ve put together, it’s heavily inspired by the ADR record format. Please feel free to use it wherever!

The Template

Author(s): NAME

Status: STATUS (Draft | Accepting Feedback | Accepted)

Last updated: DATE

Reference Link: LINK (Link to GitHub ticket, JIRA Epic, etc)

TITLE

Introduction

Overview

Goal: Make it trivial for the target audience to understand WHY this project must exist.

Focus on the core business reasons and be brief. It’s a good idea to start with this section, then when you are done with the document to double back and modify it. That way:

• You get to start the document by asking yourself why must we do this? If you can’t answer that question for yourself, there’s a good chance the reader won’t understand the value either.
• You get to come back to it later and if you can make it more brief, or if your opinions have changed you get to reflect that to the reader.

Glossary or Terminology

Goal: A section that readers will refer to while reading the document if they don’t understand a term.

Use this section to to introduce to the reader to any new:

• Terms,
• Acronyms,
• Code names,
• Any terms, names, etc that you’d like to remind the reader of

Context and Background

Goal: Provide to your reader with all the background they need to continue reading the rest of the document. Target the reader that is hearing about your proposal for the very first time and doesn’t know anything about it.

Expand on the Overview section to add comprehensive background and context to the reader.

Decision Criteria

Goal: Readers should be able to answer the question: “What business criteria are important for this decision”.

Criteria 1

Criteria’s should be concrete and ideally measurable. Examples include things like Cost , Latency, Revenue, Security

Criteria 2

Make sure to include why the criteria is particularly important. Use words like must and should consciously.

eg:

We must not regres latency beyond 200ms

The action taken should not increase our cloud storage costs

Options Considered

Goal: Convince the reader that you’ve done your due diligence and that you’ve done your research to consider other options without bias.

Option 1: OPTION_NAME

Here you get to describe each option considered

Option Breakdown

Goal: The reader should be able to answer the question: “HOW would this option address the WHY presented in the Overview section?”

Describe the option in detail, possibly link to a technical document about the option.

Pros and Cons for Option

Make sure to reference all of the decision criteria in the pros and cons. You may mention other, objective pros and cons. Your pros and cons should be in the following format:

Pros:

• Good, because X
• Good, because Y

Cons

• Bad, because Z

This section can easily introduces bias, and can easily become a dumping ground for disagreements in opinion. Thus, you aim for the following:

• Try to avoid opinions and subjective pros and cons like:
  • “Improves code quality”
  • “Makes it easy to ship new code”
  • “Will increase engineering productivity”
  • “Reduces code readability”
• Try your best to avoid being biased towards your pre-selected option. Remember that the goal from the options in the first place is to show that you’ve done your due diligence, actually do your due diligence and be prepared to change options/opinions as you write this down.
• Phrase your pros and cons against the status-quo of “Do Nothing”, it’s okay to repeat the same pros or cons for multiple options. The “Do Nothing” option itself should be an option considered as well.

Chosen Option

Goal: Make sure it’s trivial for the reader to answer the question: “Based on the decision criteria, WHAT option was selected, and WHY did the author select this option?”

Be explicit which option you are proposing, and provide any additional justification why that option is superior than others. This section is where you get to make arguments like “While option 1 is better when it comes to cost, option 2’s security considerations and impact on latency makes it superior”.

Links

Goal: Make it easy for the reader to discover documents/links external to the proposal. This is the section to link to previous proposals, a technical specification