Skip to main content
Sponsor @cloudposse

How to Document a New Design Decision

Problem​

During the course of building and managing infrastructure, lots of decisions are made along the way frequently through informal/casual conversations via Slack, Zoom calls, and whiteboarding. Persons involved in making the decisions may come and go. When new team members are onboarded, they lack all the context from previous decisions and need a way to quickly come up to speed. Plus, with so many decisions it’s hard sometimes to remember why a certain decision was made a the time. Usually, we make the best decisions based on the information, best practices, and options available at the time. However, as technology evolves, these options change and it might not be obvious anymore why a particular decision was made or even recalling what options were considered or ruled out.

Solution​

Design Decisions are anything we need to confirm architecturally or strategically before performing the implementation. They should include as much context as possible about what options are considered or ruled out. As part of this process, we’ll want to ask the right questions so we gather the necessary requirements for implementation. Once a decision is made, an should be written to capture the decision. Learn How to write ADRs.

Design Decision should be created in the Reference Architecture project in Jira and have the context defined in the Reference Architecture space in Confluence. There’s a specific way to do this so that the interlinking works appropriately. What follows are the instructions for how to do that.

Process​

  1. Identify the layer that the Design Decision is associated with.

  2. Review the other decisions to make sure there’s not one that is similar enough. In that case, we should enrich the context of that decision, rather than create a new one.

  3. Create the Design Decision.

    1. Title/Summary must always begin with “Decide on” so that our automation will automatically recognize it as a Design Decision

    2. Add the following 3 sections: (see template)

    ## Status

    Undecided

    ## Decision
    *

    ## Consequences
    *

  4. The result should look like this:


  5. After hitting “Save” you should see something that looks like this:


  6. Clicking on the title will take you to the confluence page. Add all the context there.

Step 2: Create a Document​

The document should contain all the context regarding the design decision. The context includes what options should be considered or ruled out, any pertinent questions, risks and limitations.

Review our catalog of design decisions for inspiration. Below are some examples.

References​