9

Context

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 0b10 before the length may suddenly become 0b11.
  • 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.

Problem

When I work in a team, I constantly notice that diagrams create two problems:

  1. Some people find it too difficult to change them, and don't care if they get outdated.

  2. 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.

Question

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...”

4
  • 3
    If you want high quality graphical documentation, you need people trained in creating and maintaining such documentation in your team (that is in no way different to code).
    – Doc Brown
    Dec 18, 2019 at 19:30
  • 2
    Both gliffy and draw.io allow you to embed them directly into your documentation tool. For example they have plugins for Confluence which lets you edit in place. That said the way to get more people editing diagrams is to reduce barriers--that includes process barriers. Dec 18, 2019 at 20:08
  • The only textual language I am aware of that builds diagrams is LaTeX, but that language is not friendly at all. It's used a lot in academic circles though. Dec 18, 2019 at 20:10
  • The best luck I've had keeping diagrams up to date involved doodling on old diagrams with a pen before coding and only formalizing the diagram after coding. Sometimes cocktail napkins are involved. But they were always up to date. Sadly, while coders who come later have nice formal up to date diagrams they're left clueless on how quickly update them because the evidence of how it was done is gone. Pen. Just use a pen. Dec 19, 2019 at 6:19

2 Answers 2

4

This really requires a two pronged approach: automated tools, as Ewan suggests, along with including updates to these diagrams as part of the scope of work.

Automated tools will catch the low hanging fruit, but there will be diagrams that just cannot be programmatically generated due to complexity, or needing a highly customized format. Plus, you cannot generate a diagram based on code or hardware that does not yet exist.

To a much lesser extent I encounter this daily myself. Our diagrams tend to be UML class diagrams and sequence diagrams. Tools exist to generate class diagrams from code, but they don't work so great for code not yet written. Plus it is easier to understand UML diagrams that contain only a curated subset of classes. Updating these diagrams takes time, and this adds to the work, but the team unilaterally sees the value in them. As such our team breaks things down into much smaller chunks to account for the additional time to maintain this information, which helps communicate changes in design. Being an agile project, this translates to fewer units of functionality per story point, and a larger number of stories to complete a feature.

Before estimating work, a developer needs to do a little research to identify roughly which diagrams need updating. Later this becomes a task in our sprint plan, which we usually have blocking the developer task.

Updating a diagram to go from an 8-bit CRC to a 16-bit CRC should be treated essentially the same as any other task. You need to plan for it, identify the things it depends on and the things it blocks, which gives you the order things should be done. After that the team will understand the expectations to update documentation as a normal part of the engineering process. Since they are identifying this work ahead of time it won't come as such a shock, nor will it seem like something extra. It becomes a natural step in the process for bringing a feature to life.

Don't be surprised if estimates for similar features start going up. Embrace this. Don't fight it. By having clearly defined tasks you can justify the increased estimates to management. The increased estimates will give your team the time to learn these skills and become proficient at it. Over time you may actually see the number of user facing features come back up simply because the team has had more practice. I experienced such an increase in output just last sprint, but for a kind of task unrelated to your question.

For several months we had a big focus on automated testing, which the team has been fighting for almost 4 years. I worked with the team to break down stories into pieces so small I almost couldn't believe they were stories instead of dev tasks. A feature that might have taken 2-3 stories was now 6-10 stories at triple and quadruple the total story points. Our last release was pretty dismal, but wow did the team learn a lot. Story points per sprint didn't change over this time, we just accomplished fewer features.

Suddenly, and without warning, we crushed last sprint and the team more than doubled their velocity. Turns out those 3 months of slowdowns normalized automated tests as part of our process, and the team really hit their stride. No one fought writing automated tests. It became part of the routine, and that's the key. Give the team the spare cycles to work the new thing into their routine. Give them time to form a habit.

I'm seeing story point estimates come back down now, because people have had more practice, and I think this reflects the reduction in "unknowns" in their estimates. Where it might have been be 8 points to do some dev work and write one test, now I'm seeing this come down to 3 and 5 points. You should see a similar pattern with introducing diagram updates as part of your process.

So it all boils down to:

  1. Break functionality down — way down.
  2. Research which diagrams will need updating before estimating work
  3. Plan for document updates just like any other development related task
  4. Accept reduced functionality per unit of estimate (or an overall increase in estimate per feature)
  5. And give people a chance to practice.
2

I would recommend using a tool which generates the diagram progmatically.

For example DOT syntax for graphs https://www.graphviz.org/doc/info/lang.html

or neo4j visualization

I'm sure you can find something for electrical diagrams, for more custom stuff you may have to write something. But for html docs this could be some embedded javascript.

This means one bit of hard work at the begining, but allows future editors to easily change some basic properties of the diagram with out having to draw anything

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.