Better Quality Design Docs with Graphviz

Dec 9, 2022 | HSS


Here, in the Harmonic Software Systems tactical command center (i.e. the office), our engineers have glanced upon many a design document, especially when testing avionic systems to the DO178C standard. This design is invariably a flowchart constructed using the somewhat limited power of Microsoft Powerpoint, and then copied and pasted into Microsoft Word.

Our engineers have also seen many Problem Reports (PRs – used to track the lifecycle of a problem to completion) that require a change in the design. Powerpoint is powered up, and the rest of the day is consumed by the tedious process of shifting boxes and arrows with pin point accuracy, before realising all the boxes need to be shifted across to fit onto the page.

After three or four of these design changes, our CIC (Ed) decided enough is enough, there must be a better way. One late night coding session later, and Graphviz comes to the rescue as the new defacto standard way of drawing design documents for us (and our customers) moving forward.

Now, design document updates are a breeze, changed and corrected at the touch of a button.

1.1 What is graphviz

Graphviz is a powerful, free, opensource graph visualation software. It uses a powerful DOT language to specify how a graph should be defined, and has layout engines to perform optimal arrangement of the graph’s nodes.

It produced this amazing mindmap:

Happiness Mindmap Produced In Graphviz

1.2 Installing graphviz

Installations available for Windows, Linux and OSX with full online documentation. Check out:

on Ubuntu it is as simple as :

sudo apt install graphviz

1.3 Advantages

Graphviz offers so many advantages over manual box dragging in Powerpoint:

  • quick to change and reformat flowcharts – no faff
  • simple, powerful language
  • once the layout is created, easy to copy to create the next flow chart
  • advanced layout engine for optimum placement of graphics
  • can format nodes using HTML – very powerful and versatile
  • the code can be placed into source code control for better tracability
  • large selection of node shapes to choose from:

    Diagram Showing All Possible Graphviz Node Shapes

A neat online editor can be utilised to check out work, new features and test them instantly


2 Graphviz code example

The following DOT code example…

digraph G {
  node [ shape=rectangle, style=filled, color=black, fillcolor="#a5bbe3", fixedsize="true", width="2.75", height="1.25", fontname="courier"]
  edge [ color=black ]
  start  [shape=invtriangle, style=filled, fillcolor="yellow", label="", width="0.5", height="0.25"]
  103.1  [label=<<font color='blue'>SDD-103.1</font><br/><br/>Initialize>]
  103.2  [label=<<font color='blue'>SDD-103.2</font><br/><br/>Get Pattern from<br/><font color='red'><br/>FPGA</font>>]
  103.3  [label=<<font color='blue'>SDD-103.3</font><br/><br/>Is pattern<br/>= 0x71?>, shape=diamond, width="2.7", height="2.00"]
  103.4  [label=<<font color='blue'>SDD-103.4</font><br/><br/>Return<br/>state corrupted>]
  103.5  [label=<<font color='blue'>SDD-103.5</font><br/><br/>Verify all of<br/><font color='red'>FPGA</font><br/>matches pattern>]
  103.13 [label=<<font color='blue'>SDD-103.13</font><br/><br/>Read Board<br/>ID Register>]
  103.14 [label=<<font color='blue'>SDD-103.14</font><br/><br/>Return 0>]
  103.20 [label=<<font color='blue'>SDD-103.20</font><br/><br/>Verify Board<br/>ID Register>, shape=diamond, width="2.7", height="2.00"]
  103.25 [label=<<font color='blue'>SDD-103.25</font><br/><br/>Populate<br/>Error<br/>Information>]
  103.26 [label=<<font color='blue'>SDD-103.26</font><br/><br/>Return<br/>Board ID Fail>]
  { rank=same 103.3 103.13 103.20 103.25 }
  start  -> 103.1
  103.1  -> 103.2
  103.2  -> 103.3
  103.3  -> 103.4  [xlabel=<State is other <br/>value>]
  103.3  -> 103.5  [label=<State is 0x00>]
  103.3  -> 103.13 [label=<State is<br/>0x71>]
  103.13 -> 103.20
  103.20 -> 103.14 [label="PASS"]
  103.20 -> 103.25 [label="FAIL"]
  103.25 -> 103.26

when executed and displayed:

dot -Tpng test.gv -o test.png && sxiv test.png

…produces the following chart:

Flow Diagram Generated In Graphiz

Note that this flow diagram contains SDD-103.x ids, to provide a link into the design document for further information.

Compare this with the equivalent diagram constructed using Powerpoint:

Flow Diagram Generated In Powerpoint

3 Making a change, comparing Graphviz to Powerpoint

Replicate the sloping arrows from the diamond on the left into the diamond on the right is one simple code edit:

{ rank=same 103.3 103.13 103.20 103.25 } 

Changed to…

{ rank=same 103.3 103.13 103.20 } 

…produces the following chart easily Flow Diagram Generated In Graphiz To Show Ease Of Updating

Now, attempting to replicate that change in the same time frame using powerpoint…

It is just about possible to get to this state in 5 minutes, but it’s still not right! After 7 edits, the image no longer fits the Powerpoint page size and will need to be rearranged or shrunk.

Flow Diagram Generated In Powerpoint Showing How Difficult It Is To Update

4 Conclusion

Why are you wasting time drawing boxes with Powerpoint when a free and powerful tool already exists?

We have adapted this tool to become part of our software development process, you should do the same (or employ us to do a fantastic job!)

Browse Category

Join our DO-178C group on LinkedIn

Got A Project In Mind?

We fix, develop and test embedded software for the aerospace & defence industry specialising in DO-178C safety-critical testing. Speak to us. We have laser focus, unprecedented attention-to-detail and provide phenomenal value.