Skip to content

About this Documentation

This documentation is built using mkdocs. This is a static site generation tool that takes content written in Markdown format and creates a website from it. The content it creates is static, so there's no dynamic code running on the server.

Markdown is a very simple text-based format that's easy to read and edit, whilst also having much of the functionality of HTML. It's also widely supported on platforms like GitLab or GitHub which render the files automatically.

The site is stored on GitLab here: systems/sysdoc

One of the benefits to using GitLab is that it allows us to build and test the site all within the GitLab system. It also makes it easy for anyone to view the source of the site and contribute changes.

How to contribute

If you'd like to contribute changes to the site then the process is straightforward if you have a GitLab account. It's likely that if this documentation is relevant to you then you will, but if not let us know.

Start by visiting the repository systems/sysdoc and forking a copy in to your namespace. You then have your own copy of the site that you can edit. For simple changes you can edit right in the browser, but you may want to check it out to your computer and edit there.

Any changes committed will automatically be built by the CI service on GitLab. If you look in the CI/CD section you'll see a job named pages which has the output of the build. There's also a job named lint which looks to make sure the Markdown is valid. At the end of the pages job is a URL where you can look at the site in a browser.

If you're feeling really adventurous then the mkdocs documentation shows you how to install mkdocs locally and view changes live as you're editing the content.

Ways to contribute

Here are some possible ideas for contributions:

  • Fix any simple mistakes that we've made, or improve the clarity of what we've written.
  • Update any out-of-date documentation. We could be using old screenshots or referring to old versions of software.
  • Add additional documentation for a service. Maybe you're a heavy user of a particular service, like the HPC, and would like to contribute examples for other users?
  • Make changes to the visual appearance of the site.
  • Make changes to the framework. Maybe you know something better than mkdocs and would like to show how we could use it?