ADR Viewer - adr-viewer

#### 1. Record architecture decisions

Date: 2018-09-02

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as described by Michael Nygard.

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.

#### 2. Expose command line interface

Date: 2018-09-02

## Status

Accepted

## Context

We want to maximise the usability of adr-viewer whilst maintaining flexibility in future for other output formats, e.g. a live webserver.

## Decision

The entry point for this project will be a command-line utility called `adr-viewer`. We will use the python click library to provide command-line options and documentation.

## Consequences

Click will be added as a dependency, and further improvements should consider the user experience of the command-line interface.

#### 3. Use same colour for all headers

Date: 2018-09-09

## Status

Superseded by 4. Distinguish superseded records with colour

## Context

`adr-viewer` presents all records with the same `lightgreen` header, even though records may be in different states.

## Decision

We will keep the `lightgreen` colour for everything

## Consequences

No work necessary to support ADRs superceding eachother.

#### 4. Distinguish superseded records with colour

Date: 2018-09-09

## Status

Accepted

Supercedes 3. Use same colour for all headers

Amended by 5. Distinguish amendments to records with colour

## Context

`adr-viewer` presents all records with the same `lightgreen` header, even though records may be in different states.

## Decision

Records marked as 'Superseded' will distinguish themselves from 'Accepted'

## Consequences

We must invest time thinking about the user experience for this visual indication - whether or not simply greying out is sufficient.

We must also offer a default display if logic for processing a custom linkage does not exist in this project.

#### 5. Distinguish amendments to records with colour

Date: 2018-09-09

## Status

Accepted

Amends 4. Distinguish superseded records with colour

## Context

Architecture Decision Records may be `amended` rather than `superseded` if e.g. only a small part of the decision changes.

## Decision

Amended records, although not officially supported as a distinct flag in `adr-tools`, should be distinguished from records that are either Accepted or Superseded by.

## Consequences

We now have to map 4 kinds of status to different formatting options, which presents a refactoring opportunity.

#### 6. Accessibility as a first-class concern

Date: 2018-09-10

## Status

Accepted

## Context

This tool had, up until this point, made assumptions about how its users might interpret the information it presents (for example, using colour as the main mechanism of distinguishing record types)

## Decision

Accessibility will now be a first-class concern of this project. All future design decisions should bear this in mind.

## Consequences

A base level of accessibility testing has been integrated using pa11y.

This project should be (at minimum) run through a screen reader and tested for usability.