Contributing to the documentation

Updating this documentation

This documentation uses Docusaurus. Consult their docs to learn how to use it.

To update this website

1. Navigate to Global DCC source, /docs folder.
2. Edit markdown files, commit and raise a PR.
3. If you add a new file, you need to add it to /docs/sidebars.js.
4. The CI/CD process will build the documentation in this pipeline. Check the tag (name of the build).
5. Clone the main branch of the repository GlobalDccDeploymentK8.
6. Update the file: \manifests\overlays\eu-dev\globaldcc-values.yaml
   1. update the node docs\image\tags to the lastest build tag.

If you are new to writing markdown there are cheat sheets here and here.

To preview the documentation locally,

1. Install NodeJS and yarn in your system.
2. In a command prompt, navigate to /docs folder and run yarn install and then yarn start - this will launch localhost:3000 in your browser with a preview.

PR Gateway

To ensure that reviewer can parse the changes to the documentation, we require that long lines are split and things like bullets and tables are written in the same way.

To do this we run prettier.js as part of the pr.

To get changes to the documentation to succed you'll need to:

1. Install node-js locally: https://nodejs.org/en
   • You don't need to install the c++/c/python tools for this script (but it's ok if you do)
2. Run docs/run-prettier.bat before committing
   • You might have to manually create the directory %AppData%\npm before running the script the first time. Seems to be a bug in the node-js installer they've been struggling with since 2014. If the directory isn't there docs/run-prettier.bat will fail with an ENOENT error

Editors

The documentation is written in markdown (.md files), and stored in the repository under docs\docs. A markdown file is just a text file so it can be edited with any text-editor. However it might be preferable to use an editor with a bit more features. Below are some suggestions:

• Visual Studio
  • Supports syntax highlighting
  • Has a preview functionality, that shows a realtime preview. When an md-file is open this can be accessed by clicking the preview button in the top left corner of the open document.
• Mark Text
  • Open source wysiwyg editor

The Markdown Guide

Requirements for updating the documentation

• When you add a new markdown file to the documentation also add it to the corresponding folder in the Visual Studio solutions, so it is easily accessible from VS.
• If you make a link to a section in another page, please set the id for that section explicitly, so the id do not change if the heading is changed. See https://www.markdownguide.org/extended-syntax/#heading-ids.
• If you rename/move a file you will also change its URL (unless it has a slug), make sure that any link to the page in other doc files are updated to the new URL.
• Make sure to run docs\run-prettier.bat before committing