Skip to main content

Updating Project Documentation

This guide explains how to update the documentation for an existing project (e.g., Magellan, Webbloqs, Proxies).

Conventions​

The documentation of all projects is located in the top-level docs folder of each project repository.

Project Setup​

Let's assume you want to update the documentation for the qs-magellan project.

  1. Checkout the Git repository https://bitbucket.org/quatico/qs-magellan
  2. Create a new branch with a descriptive name, e.g. docs/branch-name
  3. Make the required changes to the documentation in the docs folder.

Live Updates​

  1. If you want to test the documentation changes live, you can adjust the paths to the project's docs folder with environment variables. Copy the example file: cp .env.example .env and adjust the paths to your local repo clones. For example, adjust the value of MAGELLAN_DOCS_PATH to the local path of the qs-magellan project on your machine:

    MAGELLAN_DOCS_PATH=/Users/your-username/your-project-path/qs-magellan/docs/magellan

    You can comment out repos you're not working on - they'll use placeholder docs.

  2. Start the development server by running pnpm start in the qs-tooling-documentation project.

  3. Open the documentation site in your browser: http://localhost:3000/

Bringing the Changes Live​

Once you are happy with the changes, you can bring them live by following these steps:

  1. Create a PR
  2. Ensure the validate-documentation-changes pipeline succeeds. For example, have a look at the validate-documentation-changes pipeline.
  3. Once the PR is merged, the documentation changes will automatically be deployed to the Quatico TEST environment.
  4. To bring the changes to Prod on docs.quatico.dev, you need to run the the release pipeline.
    • this could be automated by the triggering it from the release pipeline of the project you are updating, but currently it is a manual step.