Create the Architectual Decision Record (ADR) process

Overview

As a documentation contributor, I want the context for information architecture decisions, So I can understand the intent.

As a documentation maintainer, I want to know how to create information architecture records, So I can share them with stakeholders when necessary.

Description

As described by the ADR Github Organisation:

An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) captures a single AD and its rationale; Put it simply, ADR can help you understand the reasons for a chosen architectural decision, along with its trade-offs and consequences

Within the context of NGINX documentation, ADRs will be used to record decisions for a given information architecture pattern, but will likely expand to cover other decisions with large impact, such as style guide or design system approaches.

The process for these decisions is covered by issue https://github.com/nginx/documentation/issues/413: a GitHub discussion with a specific timebox, with creating an ADR as a next step.

Creating ADRs will be an ongoing task, so the focus of this issue is to define the process for managing ADRs, then socialising their existence.

Tasks

• Decide the tools or artifacts that will be necessary for ADRs
• Create a folder in GitHub for storing ADRs
• Create three ADRs to show examples of the convention
• Share the ADRs and process with other teams

Acceptance criteria

• The user can understand what an ADR is
• The user has clear guidance on where to find ADRs
• The user can match any given documentation pattern to an ADR
• The user is able to write their own ADR with process artifacts (Templates, guidance).

Start by reading issue #413 and the linked ADR GitHub Organisation guidance; no repository files or tests are named. Define the ADR tools, artifacts, storage folder, convention, and process, then create three example ADRs and document how teams can find and write them. Done means the acceptance criteria are met and the process has been shared with other teams.