From 2dfb759d994be5f718208e7a2c21580d59926d16 Mon Sep 17 00:00:00 2001 From: Alex Wilson Date: Sat, 9 Sep 2023 15:20:27 +0100 Subject: [PATCH] docs: Republish ADRs HTML for GitHub pages --- docs/index.html | 237 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 docs/index.html diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..76a4cb8 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,237 @@ + + + + + + + + + + ADR Viewer - adr-viewer + + + + +
+

ADR Viewer - adr-viewer

+
+
+ +
+
+

+ 1. Record architecture decisions + + + + + +

+
+
+

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 + + + + + +

+
+
+

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 + + + + + +

+
+
+

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 + + + + + +

+
+
+

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 + + + + + +

+
+
+

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 + + + + + +

+
+
+

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.

+
+
+
+ +
+ + + \ No newline at end of file