Version control

Use a version control system (such as Git), this allows you collaborate with others, and go back in history and see when changes were made, what changes were made, why they were made and by who they were made by with the commit message explaining the rationale behind the decision.

Example commit messages:

• Add composition edge from node Foo to Bar
• Remove node Bar
• Add dependency from Bar on Baz

Header documentation block

The diagram source can end up in different places and people may have an outdated version, or have some feedback or questions, so it might be a good idea to have a header documentation block containing some metadata. Graphviz supports C++-style comments: /* */ and //, it also considers lines starting with a # character to be output from C preprocessor and discarded. PlantUML supports comments using '.

If the diagram is a UML diagram the documentation can specify what type of UML diagram it is, example a class diagram, component diagram, or sequence diagram, etc.

It can include date of creation, date of last modification, and author along with contact information. It can contain a link to where the latest version of the diagram may be acquired.

It can include a SPDX license identifier, such as CC-PDDC for example.

It can include which version it is, if the diagram is for a particular software implementation it can use the same version as for that software, else semantic versioning is probably a bad idea, and you should consider using a sequentially-incremented integer or just a date instead.

Example:

' UML component diagram illustrating the architecture behind Acme Labs Project Z.
' The architecture derives from the earlier Project X.
' Designed by the Acme Technical Committee 1 (TC1) on August 2011.
'
' Author: Alice <[email protected]>
' Created on: 2011-10-01
' Last updated: 2020-12-12
' Website: https://www.example.com/diagrams/
' License: CC-PDDC

Graphviz

Use the .gv file extension. The MIME type is text/vnd.graphviz.

You can style nodes of same type together.

// Style first
node1, node2, node3 [shape="box", color="blue"]
node4, node5, node6 [shape="circle", color="red"]

// Declare the edges later
node1 -> node2 -> node3
node4 -> node5 -> node6

You can use the class attribute on nodes to use CSS classes from an external stylesheet file. Note, this only works when rendering as SVG.

alice [class="girl"]
bob [class="boy"]
clare [class="girl"]

alice -> bob -> clare

Use indention:

Good 👍️

subgraph { 
  rank = same; A; B; C; 
}

Bad 👎️

subgraph { 
rank = same; A; B; C; 
}

PlantUML

Use the .puml file extension.

You can nest structures in PlantUML, this allows you group them easier in one cohesive structure.

Good 👍️

@startuml
frame FrameA {
  component ComponentA {
    component Foo
  }
  component ComponentB {
    component Bar
  }

  ComponentA -> ComponentB
  Foo -> Bar
}
@enduml

Bad 👎️

@startuml
frame FrameA {
  component ComponentA {
    component Foo
  }
  component ComponentB {
    component Bar
  }
}
ComponentA -> ComponentB
Foo -> Bar
@enduml