docs-onboarding/documentation-guidelines.md

Documentation Guidelines

Best practices and guidelines for writing code documentation.

Formats

All documentation should be easy maintain and accessible. Easy formats should be preffered over more complex ones.

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