Contributing documentation

The documentation is written as a collection of markdown files, which are then converted to a website using mdbook.

Branching rules

  • The main branch is where the current version of the documentation is built from. All development branches should be based on this branch.
  • Branches with pages/ prefix contains in-progress work on specific page or section. For example, improvements to the user guide has the name of pages/user-guide.
  • Branches with issue/ prefix contains in-progress work relating to a bug. This could be typos, grammar and writing style or deployment issues.
  • The gh-pages branch contains the compiled site files built from main branch. This branch is automatically built using a GitHub action, and they should not be modified or branched from.

File structure

book.toml

This file contains the configuration for mdbook. You shouldn't need to change anything here.

src

This directory contains all source markdown files, images, code or any files that will be included in the compiled site.

src/SUMMARY.md

This file creates the table of contents that you see in the sidebar. See the mdbook documentation for its syntax.

book (local build only)

This directory is automatically generated using mdbook's build commands. It contains the site's build artefacts.

Other

  • src/images contains all images of the site.
  • src/code contains all code files that is included in the documentation using the {{#include}} directive.

Contribution workflow

  1. Create a branch from main
    • If you don't have push access to the repositories (which, unless you're a maintainer you likely won't), you may need to fork the repository first.
  2. Read and understand the build process outlined in the "Editing, Building, Local Deployment" section of README
  3. Work on the branch
  4. Create a pull request
    • Follow the instructions given in the provided template
  5. Wait until one of our maintainers approved your PR and merge it to main
  6. The site will be rebuilt, and your changes will be published.

Things to keep in mind

All contributions will be released under the ISC license. Please ensure that any third-party code used is compatible with this license.

When commenting or creating PRs, please follow the GitHub community guidelines.