Better Quality Design Docs with Graphviz

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.

The following DOT code example…

digraph G {
  overlap=false;
  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:

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:

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

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.

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

https://graphviz.org

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!)