Skip to main content

Contribution Guidelines

How to Add Things?

General​

You can either contribute to this documentation:

  • Over the Web UI and creating changes in the docs folder and submitting a merge request.

  • Or directly with Git and creating a branch on main with name

    • feat/... for new content or
    • fix/... for typos and other things.

Add New Content​

Use the template here topic.md to write a new markdown file or use an existing one. Sort the document into a folder here

Copy the template from here

Add BPA Meeting Notes​

Use the template here meeting.md to write a new meeting note inside here.

Copy the template from here.

Writing​

  • Documentation is written in English and in Markdown

  • All titles & subsections are written capitalized. See explanations. E.g.

    • # Additional resources is wrong and should be either # Additional Resources and better # Resources.
    • # How Is This Achieved? and not # How is this achieved?

  • All terminology/names which refers to code (programs, commands, file paths, etc.) must use a monospace font, e.g. verbatim. Some examples:

    • Commands: mkdir -p docs and not "mkdir -p docs"
    • Paths: docs/file.md and not "docs/file.md".
    • Terminology: "A glob pattern like *.sh" and not "A glob pattern like *.sh"

  • Use simple English. Try to avoid filler words.

  • Be precise. Introduce abbreviations once. Use an existing tag or suggest a new one in the frontmatter for it too.

  • Do not reinvent the wheel: Refer to official documentation. Reinvent for meta-documentation, i.e. gathering stuff on certain topics.

  • Format your document. You can request formatting on a merge request.

info

In the future we would like to add the following checks on CI:

  • Feedback on typos & grammar and wrong/missing links.

Request a Format From CI​

If you commit like this on your branch

git commit --allow-empty -m "fix: trigger format" -m "CI: format"
git push

the CI will then run the format and commit back onto your branch, where you can git pull to inspect the changes. The next CI run should pass the format stage.