Update README and CONTRIBUTING guidelines

CONTRIBUTING.md

@@ -1,90 +1,120 @@
 # Contributing
 
-Markdown code in this repo must pass several static analysis tests, which are
-detailed below. Note that you can run:
+You're welcome to suggest changes if you spot a broken link or typo. Clone the repo or use the GitHub UI to make a PR.
+
+## Installation
+
+You'll need a few tools to make and test your changes before pushing them to a PR.
+
+### Prettier
+
+All Markdown should be formatted with [Prettier](https://prettier.io/) version 3.1
+Install with:
 
 ```sh
-make ci
+npm install -g [email protected]
 ```
 
-to run these checks before pushing to Github.
+Once installed, ensure your editor runs Prettier on a pre-save hook:
 
-## Git commit subjects
+- [PyCharm instructions](https://www.jetbrains.com/help/pycharm/prettier.html)
+- [VSCode instructions](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- [Vim instructions](https://prettier.io/docs/en/vim.html)
 
-Git commit subjects must:
+Prettier conformance is checked in CI and configured via `.prettierrc.yaml` and
+`.prettierignore`.
 
-- Be no longer than 70 characters;
-- Start with a capital letter;
-- Not end with a full stop;
+### Docker
 
-Further, pull request branches should rebase off `main` to incorporate upstream
-changes; don't merge `main` into your branch.
+### Pyenv
 
-These rules are checked using Pytest in CI.
+## Development
 
-## Formatting
+### Run CI tests locally
 
-All markdown should be formatted with [Prettier](https://prettier.io/) version 3.0.0
-This can be installed on your host OS with:
+If your changes include Markdown, be aware that Markdown code in this repo must pass several static analysis tests. Before pushing to GitHub, run
 
-    npm install -g [email protected]
+```sh
+make ci
+```
 
-Once installed, ensure your editor runs Prettier on a pre-save hook:
+to run these checks.
 
-- [PyCharm instructions](https://www.jetbrains.com/help/pycharm/prettier.html)
-- [VSCode instructions](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
-- [Vim instructions](https://prettier.io/docs/en/vim.html)
+### Git commit subjects
 
-Prettier conformance is checked in CI and configured via `.prettierrc.yaml` and
-`.prettierignore`.
+Git commit subjects must:
+
+- Be no longer than 70 characters.
+- Start with a capital letter.
+- Not end with a full stop.
+
+Further, PR branches should rebase off `main` to incorporate upstream
+changes; don't merge `main` into your branch.
+
+These rules are checked using Pytest in CI.
 
-## Spelling
+### Spelling
 
 Pull requests must pass a spell-check before merge. This is done using the
 [`tmaier/markdown-spellcheck`](https://hub.docker.com/r/tmaier/markdown-spellcheck)
 Docker image.
 
 To run the spell-test locally run:
 
-    make spell_check
+```sh
+make spell_check
+```
 
 or:
-
-    docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \
-        --report --ignore-numbers --ignore-acronyms "**/*.md"
+```sh
+docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \
+    --report --ignore-numbers --ignore-acronyms "**/*.md"
+```
 
 Add exceptions to the custom dictionary in `.spelling`.
 
-## Linting
+### Linting
 
 Markdown files are linted by
 [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli).
 
 To run the linting locally run:
 
-    docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0
+```sh
+docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0
+```
 
 or, if installed on your host OS, run:
 
-    markdownlint .
+```sh
+markdownlint .
+```
 
 or:
 
-    make markdownlint
+```sh
+make markdownlint
+```
 
 Configuration for the enforced rules is in `.markdownlint.yaml`.
 
 Many linting issues can be fixed by running:
 
-    markdownlint --fix .
+```sh
+markdownlint --fix .
+```
 
 ## Preview rendered pages
 
 You can use [`grip`](https://github.com/joeyespo/grip) to render Github-flavour
 markdown files. Install with:
 
-    brew install grip
+```sh
+brew install grip
+```
 
 While working on docs, run a local, auto-reloading server with:
 
-    make server
+```sh
+make server
+```

README.md

@@ -11,7 +11,7 @@ the complete set of Kraken Tech coding conventions, you'll need to [apply for a
 here][jobs] 😜.
 
 [group]: https://octopusenergy.group/
-[jobs]: https://jobs.lever.co/octoenergy?department=Kraken%20Technologies%20%F0%9F%93%88
+[jobs]: https://kraken.tech/jobs
 
 Contents: