Merge pull request #34 from dxw/docs/add-to-docs

Add to docs

README.md

@@ -4,31 +4,63 @@ This is a rebuild of the airTEXT.info service
 
 1. [Getting started](/doc/getting-started.md)
 
-## Static code analysis
+## Description of the service
 
-Run [Brakeman](https://brakemanscanner.org/) to highlight any security
-vulnerabilities:
+A service for providing forecasts and personalised alerts on air quality and
+other environmental factors in:
 
-```bash
-$ brakeman
-```
+- Greater London
+- Cambridge
+- the Chelmsford/Colchester area
+
+## Terminology
+
+We aim to use and refine a "ubiquitous language" for use throughout the service.
+We believe that this will optimise our communication and minimise our
+misunderstandings and our cognitive load. We will aim use the same terms in:
+
+- the UI of the service
+- the code we write
+- our sketches and mockups
+- our research sessions
+- our documentation and our presentations to partner organisations
+
+See [./doc/terminology.md][]
+
+## Tests
 
-To pipe the results to a file:
+### Local unit and integration tests
 
-```bash
-$ brakeman -o report.text
+#### Fast feedback loop
+
+These tests (Rspec and Capybara) can be run at maximum speed with:
+
+```sh
+bundle exec rspec
 ```
 
-## Making changes
+### Full pre-commit checks
+
+Before committing you should run our complete set of checks and tests.
 
-When making a change, update the [changelog](CHANGELOG.md) using the
-[Keep a Changelog 1.0.0](https://keepachangelog.com/en/1.0.0/) format. Pull
-requests should not be merged before any relevant updates are made.
+Choose from either the dockerised or undockerised version of the supplied
+comprehensive test script which includes:
 
-## Releasing changes
+- formatting files with `prettier`
+- checking scripts with `shellcheck`
+- linting Ruby files with `standardrb`
+- linting JS with `eslint`
+- linting CSS with `stylelint`
+- running automated test suite with `rspec`
+- running API specs and generating OpenAPI spec via the
+  `rswag_api_tests_with_docs` `rake` task
+- analysing vulnerabilities in Ruby gems with `brakeman`
 
-When making a new release, update the [changelog](CHANGELOG.md) in the release
-pull request.
+e.g.
+
+```sh
+./script/no-docker/test
+```
 
 ## Architecture decision records
 
@@ -61,9 +93,14 @@ To manage sensitive environment variables:
 
 ## Access
 
-TODO: Where can people find the service and the different environments?
+The service is deployed to Heroku at
+[https://air-text-3e4548b53179.herokuapp.com/][].
 
 ## Source
 
 This repository was bootstrapped from
 [dxw's `rails-template`](https://github.com/dxw/rails-template).
+
+[https://air-text-3e4548b53179.herokuapp.com/]:
+  https://air-text-3e4548b53179.herokuapp.com/
+[./doc/terminology.md]: ./doc/terminology.md

doc/terminology.md

@@ -0,0 +1,46 @@
+# Terminology
+
+## Purpose
+
+We aim to use and refine a "ubiquitous language" for use throughout the service.
+We believe that this will optimise our communication and minimise our
+misunderstandings and our cognitive load. We will aim use the same terms in:
+
+- the UI of the service
+- the code we write
+- our sketches and mockups
+- our research sessions
+- our documentation and our presentations to partner organisations
+
+## Terms
+
+We are provided with daily **`forecasts`** by CERC. Each forecast consists of 6
+environmental **`predictions`**:
+
+- Air pollution
+- UV
+- Pollen
+- Temperature
+- Wind
+- Rain
+
+Each **prediction** has an **`DAQI level`**. This [DAQI (Daily Air
+Quality Index)][] scoring uses the range 1-10:
+
+- low (1-3)
+- moderate (4-6)
+- high (7-9)
+- very high (10)
+
+An **`alert`** is in effect when a particular prediction's DAQI level is above a
+certain threshold e.g. tomorrow the:
+
+- UV prediction has the **moderate** DAQI level
+- pollen prediction has the **low** DAQI level
+- air pollution prediction has the **high** DAQI level (aka an "**Air quality
+  alert**: high")
+
+**Air quality alerts** are air pollution predictions with DAQI leveles above
+"low".
+
+[DAQI (Daily Air Quality Index)]: https://uk-air.defra.gov.uk/air-pollution/daqi