docs-onboarding/documentation-guidelines.md

Documentation Guidelines

Best practices and guidelines for writing code documentation.

Release Notes

The idea is to get rather automated release notes. To have this as easy as possible, we need:

• key words for the kind of change we applied:

  • new: - for newly added functionality
  • update: - for updated functionality
  • fix: - for fixed functionality
  • delete: - for removed functionality
  • Everything else will be ignored

• tags for each version, we will output only the change log from the last and second last tag

  • you can add tags with git tag -a <tag> -m "<message>"

resources/scripts/release-notes.bash is an example bash script to generate the release notes. You can run it with the following command:

bash resources/scripts/release-notes.bash

PlantUML

Create png images from PlantUML files using the following command:

plantuml -tpng <file>.puml

Draw.io Diagrams

Ensure to have the draw.io application aliased. This example is for a macOS based system configured with ansible:

- name: Add Draw.io alias to .zshrc
  lineinfile:
    path: "/Users/{{ macos_user }}/.zshrc"
    line: "alias drawio='/Applications/draw.io.app/Contents/MacOS/draw.io'"
    state: present

Create png images from Draw.io diagrams using the following command.

drawio -x -f png -b 10 -o <output>.png <file>.drawio