I am a strong proponent of clear, illustrative diagrams in documentation. When they are properly done, they improve a lot two aspects: the understanding of the documentation and the time a developer spends reading the documentation when he needs to recall something he already have read.
The only tool I found which (1) is online (nothing to install), (2) is easy to use, (3) doesn't impose specific constraints (as opposed to UML tools), (4) and allows to embed vector info inside a PNG image for future editing is draw.io. While it is practical, like any online drawing tool, it has one major drawback for the specific usage of diagrams embedded in documentation: once the diagram is made, it takes extra steps to modify it, compared to the steps it takes to modify text within a Markdown file.
The problem is that sooner or later, things change. Take, for instance, this diagram which illustrates a part of the protocol I developed to communicate with Arduino devices:
More than one thing may change:
- I may decide that I don't need CRC any longer. Or that CRC should take 16 bits instead.
- Or the magical two-bit value
0b10before the length may suddenly become
- Or “area” in the second row may be renamed to “category.”
- Or it may make sense to put the line block before the level and the area blocks.
Here's another example:
Here, I may want to:
- Change a resistor,
- Change the pins,
- Add or remove components,
- Change the color of a LED.
If I perform one of those changes, I have a choice:
- Either I download the PNG, go to draw.io, import the PNG, edit it, export it, move it to the directory where it belongs and commit my changes. This could take a few minutes.
- Or I keep the diagram outdated, which would mean that I couldn't trust any of my diagrams for the old projects a few years later.
- Or I get rid of the diagram, and later, I need to read the textual description instead of just glimpsing over the image.
When I work in a team, I constantly notice that diagrams create two problems:
Some people find it too difficult to change them, and don't care if they get outdated.
Some people are afraid that the diagrams would be outdated, and so they chose another strategy: avoid a change or a refactoring which would make the code different from the diagram. Essentially, if it makes sense in the project corresponding to the first diagram to rename “area” to “category,” they will keep the term “area,” because the change is just too complex. Or if it makes sense to switch to 16-bit CRC, they will invent the reasons to keep a 8-bit CRC.
I understand those people completely, and I occasionally do exactly the same.
My question is, what could be done, either at technical or at human level, to prevent or at least reduce those situations, in order to encourage the projects to have great, up to date diagrams, without the fear to change things which are included in the diagrams?
The answers I'm looking for could be something like: “Well, you can use this or that to magically generate the diagrams on the fly based on a configuration file...” or “You can do this or that to make people believe that updating diagrams is easy and should be part of their daily work...” or “You can parse the diagrams and match them to the source code in order to fail the build if they are outdated...”