3SD handbook

Contributing

Everyone is welcome to contribute to this handbook. You can edit a page by clicking on the Edit this page link at the bottom of the page.

Please use issues and merge requests in the standard way to suggest and make edits to content.

Style guide

Use heading levels 1, 2 and 3 only.

Only use 1 level of subdirectories (think sections and chapters).

Technology

All content is written in MarkDown. See http://markdown-it.github.io/ for more details and examples.

This handbook is powered by https://vitepress.vuejs.org/.

The sidebar is defined in the config.

Local development

You can set up a development copy of the published site if you like. A local development site is not needed to contribute - you can do everything via Gitlab, but it might be helpful if you are making a lot of changes to the handbook.

You will need to have git and an up to date version of node installed locally and a copy of your public ssh key on Gitlab.

  1. Clone the repo with git clone ssh://git@lab.3sd.io:2222/internal/handbook.git.
  2. From the handbook directory (cd handbook) run npm install.
  3. Start the development server with npm run dev.
  4. Visit http://localhost:3000/ to see the dev site.
  5. The dev site will automatically update as you make changes to the source text locally.

Step-by-step guide for beginners

  1. Before starting any edits, create a ‘merge request’ in the issue ticket that it relates to (in the Staff Handbook project). This will start a new branch.
  2. To get it in VS Code, you first need to do a ‘fetch’ - go to 'Source Control' (3rd icon down on left hand sidebar) → drop down menu (three dots in the top right corner of sidebar) → ‘pull & push’ → ‘fetch’
  3. Then switch to the branch → at the bottom of VS Code there is a blue bar - click on the left hand side and search for the new branch (the name of the issue ticket).
  4. To view the site locally - follow the steps above (in Local Development) and you can view the handbook at http://localhost:3000/
  5. When the text is ready to commit, review it in ‘Source Control’. When you’re happy, add it (+) to ‘changes’ (i.e. stage commit) and write a message. Then push the up arrow at the bottom of the page (in blue) to push the commit.
  6. When you want someone to review the commits, change the issue merge request ticket from ‘draft’ to ‘ready’ (top right hand drop down) and then set the person you want to be the ‘reviewer’ (which is below the ‘assignee’ field in the sidebar). They will then review your commit and can make edits or merge it straight to master. The changes will then appear on the Staff Handbook.