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.

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

Folder Structure

If you want to add an optional folder structure to your documentation, you can use the following command to generate a tree-like structure.

ls -R | grep ":$" | sed -e 's/:$//' -e 's/[^-][^\/]*\//--/g' -e 's/^/   /' -e 's/-/|/'     

Example output:

   |-know-how
   |-resources
   |---diagrams
   |---images
   |---scripts