Documentation tooling

- 5 mins read

Requirements for tools and documentation

  • Open source tooling
  • Editable with vim, emacs, etc
  • Suitable for version control
  • Suitable for scripting

Types of documentation

Component diagrams

Preferred tool : PlantUML

Note PlantUML requires graphviz to be installed to generate component diagrams.


# Command line
java -jar $PLANTUML -v -tpng src/k8s-runtime.uml -o ../out/

title Kubernetes
skinparam componentStyle uml2

package "Development" {
  component Developer
  component [Code\nVCS] as VCS
  component CI
  component CD

package "External Services" {
  component MQ
  component DB

package "Kubernetes Cluster" {
  component "Nodes/Pods/Containers" as Service
  component [Controller] as Controller

package Artifacts {
  component [Container Registry] as Registry
  component [Config VCS] as Config

package "External Network" {
  component [User] as WebBrowser

Developer -l-> VCS : commit
VCS -d-> CI : test & build
CI -r-> CD
CI -d-> Registry : upload image
CD -r-> Controller : deploy

WebBrowser -u-> Service

Service -u-> MQ
Service -u-> DB

Controller -r-> Registry : fetch
Controller -d-> Config : fetch

Controller -l-> Service : deploy


Useful parameters for Component Diagrams

skinparam componentType uml2

skinparam linetype splines
skinparam linetype ortho
skinparam linetype polyline

Sequence diagrams

Preferred tool : PlantUML

Note: PlantUML can generate sequence diagrams using only the plantuml.jar file.



title Data flow

entity "Data Source" as DataSource

box "Integration" #lightblue
  entity "fluent-bit" as fluentbit
  entity "envoy" as envoy
end box

box "Monitoring"
  entity "Prometheus" as Prometheus
  entity "Grafana" as Grafana
end box

box "Splunk Platform" #lightblue
  entity "Splunk\nHeavy Forwarder" as HF
  database "Splunk Index" as IDX
  entity "Splunk SHC" as SHC
end box

actor "User" as User

== Events ==

DataSource -> fluentbit
fluentbit -> envoy : HTTP-Proxy/HEC
envoy -> HF : HTTP/HEC
HF -> IDX : TCP/Splunk forward

== Metrics ==

envoy -> Prometheus : metrics
fluentbit -> Prometheus : Metrics over HTTP

== Reporting ==

Prometheus -> Grafana
Grafana -> User : HTTP
SHC -> User : HTTP


Timing diagrams

Preferred tool : PlantUML



robust "CPU0" as CPU0
robust "CPU1" as CPU1
concise "Task Progress" as TaskProgress
concise "Task Breakdown" as TaskBreakdown

TaskProgress is Idle
TaskBreakdown is None
CPU1 is Idle
CPU0 is Idle

TaskProgress is Running
TaskBreakdown is Serial
CPU0 is PreparingTask
CPU1 is Idle : Idle

CPU0@100 <-> @200 : 100 ms

TaskBreakdown is Parallel
CPU0 is NumberCrunching
CPU0 -> CPU1 : Distribute task
CPU1 is NumberCrunching

TaskProgress is Idle
TaskBreakdown is None
CPU1 -> CPU0 : Complete task
CPU0 is Idle
CPU1 is Idle

CPU0 is Idle
CPU1 is Idle

Graph visualization

Preferred tool : Graphviz


 ~$ neato src/ -Tpng -o out/graph-cohesion.png
digraph G {

  {node [label="Developer" style=filled color=skyblue] d1 d2 d3 d4 d5 }

  d1 -> d2 [len=2];
  d1 -> d3 [len=2];
  d1 -> d4 [len=2];
  d1 -> d5 [len=2];

  d2 -> d1 [len=2];
  d2 -> d3 [len=2];
  d2 -> d4 [len=2];
  d2 -> d5 [len=2];

  d3 -> d1 [len=2];
  d3 -> d2 [len=2];
  d3 -> d4 [len=2];
  d3 -> d5 [len=2];

  d4 -> d1 [len=2];
  d4 -> d2 [len=2];
  d4 -> d3 [len=2];
  d4 -> d5 [len=2];

  d5 -> d1 [len=2];
  d5 -> d2 [len=2];
  d5 -> d3 [len=2];
  d5 -> d4 [len=2];


Flow charts

Preferred tool : PlantUML

Flow chart


scale 4

:Perform task;
note right
E.g. Manually resize a volume
end note
if (OK?) then
  -[#blue]-> p=**0.97**;
  :Task complete;
  -[#blue]-> Info;
  #Lightblue:Success1 = 0.97;
  -[#red]-> p=**0.03**;
  :Emergency with plan;
  note right: Follow rollback procedure
  if (Recover?) then
    -[#green]-> p=**0.90**;
    #Lightgreen:Abort1 = (0.03 * 0.90);
    -[#red]-> p=**0.10**;
    :Emergency without plan;
    if (Recover?) then
      -[#green]-> p=**0.70**;
      #Lightgreen: Abort2 = (0.03 * 0.10 * 0.70);
      -[#red]-> p=**0.30**;
      #Pink: Failure1 = (0.03 * 0.10 * 0.30);



Preferred tool : gnuplot


 ~$ gnuplot src/plot-usl-001.gnuplot
set terminal pngcairo size 1000,800 enhanced font 'Verdana,14'
set output 'out/plot-usl-001.png'
set border linewidth 1.5
set title "Scalability - Full USL"

set ylabel 'Work'
set xlabel 'Scale'

# Axes
set style line 11 lc rgb '#808080' lt 1
set border 3 back ls 11
set tics nomirror out scale 0.75

# Grid
set style line 12 lc rgb'#808080' lt 0 lw 1
set grid back ls 12

set style fill noborder
set style function filledcurves y1=0
set clip two

n = 1
s = 0.1 # serialization
k = 0.01 # crosstalk

USL(x, s, k) = (x * n) / (1 + s * (x - 1) + k*(x*(x-1)) )

f1(x) = USL(x, 0, 0)
f2(x) = USL(x, s, 0)
f3(x) = USL(x, s, k)
f4(x) = USL(x, 0, k)

set yrange [1:10]
set xrange [1:40]

unset colorbox
set key opaque
set key title "(xn) / (1 + s(x-1) + k(x(x-1)) )"
set key top right Left reverse samplen 1

set label "Linear scalability" at 10,9.2 front
set arrow from 7,6 to 10,9

set label "Serialization constrained" at 25, 5.5 front textcolor rgbcolor "#ffffff"
set label "Coordination constrained" at 6, 4 front textcolor rgbcolor "#ffffff"
set label "Serialization and coordination constrained" at 8, 2 front textcolor rgbcolor "#ffffff"

set lmargin 6
plot f1(x) fs transparent solid 0.30 lc rgb "light-green" title 'n=1   s=0     k=0', \
     f2(x) fs transparent solid 0.50 lc rgb "blue" title 'n=1   s=0.1  k=0', \
     f4(x) fs transparent solid 0.50 lc rgb "light-red" title 'n=1   s=0     k=0.01', \
     f3(x) fs transparent solid 0.70 lc rgb "red" title 'n=1   s=0.1  k=0.01'


Preferred tool : pandoc

pandoc src/ \
--mathml  \
-t beamer \
--highlight-style espresso \
-o out/presentation.pdf


Preferred tool : pandoc

pandoc src/ \
 -V geometry:margin=1in \
--latex-engine=pdflatex \
--mathml  \
--highlight-style espresso \
-o out/report.pdf

Other tools