Improving this handbook

You are welcome to make improvements to this handbook. Please follow the process below.

1. Create an issue with details of the improvement so it can be discussed quickly before you get started
2. Create a merge request with your changes
3. Once you're happy with the changes assign the merge request to someone for review
4. Once approved, merge the changes and publish them (see below for details)

This handbook is written in MarkDown (a simple text format suitable for documentation) and built with VitePress (a popular tool for documentation). See the VitePress guide for more information.

Style guide

Please follow these style guidelines when contributing.

Language

Use plain english wherever possible. Assume a tecnical audience and use relevant technical terms when appropriate but strive to keeps things simple and understandable and avoid unnecessary jargon.

Headers

A Heading 1 (#) should only appear as the title at the beginning of each page. Inside a page, use Heading 2s (##) and Heading 3s (###). If you find yourself reaching for Heading 4s (or 5s ot 6s!) think instead about simplifying the hierarchy.

Bulleted lists

Don't overuse bullets - avoid bulleting text that could just as easily be written as paragraphs.

Avoid going more than two bullets deep.

Use - as the bullet prefix.

Tables

Avoid tables, especially ones with lots of columns as they are hard to read and edit in Markdown and don't work well on mobile devices.

Consider using bulleted lists or headings in place of tables.

Local development environment

You can set up a local development copy of the handbook which will allow you to preview changes and identify any technical issues in the change.

You will need node and pnpm installed locally.

1. Clone the repo with git clone ssh://git@lab.3sd.io:2222/internal/handbook.git.
2. From the handbook directory (cd handbook) run pnpm install.
3. Start the development server with pnpm run dev.

Checking the build

Before pushing a change for review, you can check for any errors (e.g. dead links and invalid syntax) by running pnpm build. You should fix any reported errors before submitting a merge request for review.

Publishing updates

Once a request is merged, it needs to be published. Follow the instructions below or ask someone to do so for you.

From the handbook directory on elm (elm.3sd.io:src/handbook) run:

git pull
docker-compose up -d --build