Date: 2018-09-02
Accepted
We need to record the architectural decisions made on this project.
We will use Architecture Decision Records, as described by Michael Nygard.
See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.
Date: 2018-09-02
Accepted
We want to maximise the usability of adr-viewer whilst maintaining flexibility in future for other output formats, e.g. a live webserver.
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.
Click will be added as a dependency, and further improvements should consider the user experience of the command-line interface.
Date: 2018-09-09
Superseded by 4. Distinguish superseded records with colour
adr-viewer presents all records with the same lightgreen header, even though records may be in different states.
We will keep the lightgreen colour for everything
No work necessary to support ADRs superceding eachother.
Date: 2018-09-09
Accepted
Supercedes 3. Use same colour for all headers
Amended by 5. Distinguish amendments to records with colour
adr-viewer presents all records with the same lightgreen header, even though records may be in different states.
Records marked as 'Superseded' will distinguish themselves from 'Accepted'
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.
Date: 2018-09-09
Accepted
Amends 4. Distinguish superseded records with colour
Architecture Decision Records may be amended rather than superseded if e.g. only a small part of the decision changes.
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.
We now have to map 4 kinds of status to different formatting options, which presents a refactoring opportunity.
Date: 2018-09-10
Accepted
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)
Accessibility will now be a first-class concern of this project. All future design decisions should bear this in mind.
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.