alphagov / re-team-manual

Team manual for Reliability Engineering and its sub-teams.

Reliability Engineering Team Manual

Technical documentation

This is a static site generated with Middleman.

Tech docs template

This project uses alphagov/tech-docs-template.

Dependencies

• Ruby.
• The middleman gem.

Making changes

To make changes, edit the source files in the source directory. To add a completely new page, create a file with a .html.md extension in the /source directory.

Whilst writing documentation we can run a middleman server to preview how the published version will look in the browser. After saving a change the preview in the browser will automatically refresh. Run bundle exec middleman server, then the website will be available locally at http://localhost:4567.

Building the project

Build the site with:

    bundle exec middleman build

This will create a bunch of static files in /build.

Deployment

This is deployed automatically to the PaaS via the multi-tenant Concourse via the internal-apps pipeline in the tech-ops repo. (The Autom8 team is a good place to start with any questions).

Licence

MIT License

Pre-commit hooks

There are pre-commit hooks available to help when creating or editing markdown.

Install pre-commit and the vale linter:

brew install vale pre-commit
pre-commit install

The styles are copied from https://github.com/alphagov/govuk-developer-docs/tree/bc94d39dce23236fc61238464010713daf5213f9/styles

re-team-manual's Issues

Add CI

• This is a private repo, so we'd have to pay money to Travis, I believe, if we wanted CI that everyone can see.
• We could add a Jenkinsfile applicable to GOV.UK, to run on the GOV.UK Jenkins, but this is the RE team manual.
• Does RE have a CI solution yet? Could this run on a pilot of that?
• It'd be good to have Vale (#1) run on CI, as then people who are writing things don't have to install pre-commit hooks or remember to run the linter on their changes.

Add Vale for documentation linting

Vale is a great tool for linting your documentation to catch common syntax errors and easier ways to phrase things. It's in use on the GOV.UK Developer docs. We should add it here to ensure a consistent style from the beginning.

Add content

Probably the most important bit of a team manual - adding content for it.

I propose:

• A section for RE ways of working and ceremonies as a whole.
• A section for GOV.UK-specific things (eg the GOV.UK RE interruptible rota), linking out to the GOV.UK Developer Docs where necessary.
• A section for Verify-specific things (eg the Verify Yak docs?), linking out to the Verify Team Manual where necessary.
• A section for Tools-specific things, linking out to docs repos they have where necessary.

Of course, it's important that everyone has input on each of the sections, especially the first one, otherwise new people joining will feel disconnected. This is an evolving manual as RE the team matures, of course. It won't be right on the first pass.