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.

Markdown

Markdown is the easiest format to write and read. It is recommended to use markdown for all documentation as long as more complex formatting is not needed.

AsciiDoc

AsciiDoc allows more formatting and can create more official looking documents.

It is recommended to write a pipeline template to easily convert AsciiDoc files to PDFs. Thre we can also have an AsciiDoc template specifiying the look of the PDF. The pipeline template then makes it easy to consume the pdf creation functionality.

To manually create a PDF from an AsciiDoc file, you need asciidoctor and use the following command:

asciidoctor-pdf -a pdf-theme=my-theme.yml example.adoc

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.

git ls-tree -r --name-only HEAD | sed 's|[^/]*|   &|g'

Example output:

   Dockerfile
   maus_helper.sh
   maus_loader.yml
   requirements.txt
   setup.py
   src/   __init__.py
   src/   logging_config/   __init__.py
   src/   logging_config/   config.py
   src/   maus_loader.py
   src/   scraper/   __init__.py
   src/   scraper/   scraper.py
   tests/   __init__.py
   tests/   test_scraper.py

2 KiB Raw Permalink Blame History