Alex Masycheff, Intuillion Ltd.
Do you sometimes feel, when reading a long multi-step procedure with multiple choices, that you’d rather see it as a flowchart that graphically shows what you need to do?
Well, you are not alone. The proverb “A picture is worth one thousand words” exists for a reason.
Drawing Manually Is Too Much Work
Drawing pictures alone was never a problem. There are plenty of tools that let you create nice looking flowcharts and diagrams. The problem arises when a diagram includes parts that vary depending on the product, and your company has many of them. Suppose you are documenting a troubleshooting procedure that helps the user fix a problem in the washing machine. There are various models of the washing machine that provide different features. A troubleshooting for one model may be 80 percent the same as for another model. But because some components or features available in one model might be unavailable in another one, certain steps or checks in the troubleshooting will also look different.
Even if your tool allows you to somehow conditionalize parts of the diagram (a while ago, I figured out how to “conditionalize” parts of a diagram in Visio using layers) and then hide or expose them depending on the specific product, you still have to maintain both the textual description of the troubleshooting piece and the diagram.
Ideally, troubleshooting documentation that addresses a specific problem, occurring in a specific product in a specific context, should be assembled automatically and presented to you in the way you want, either as text or a flowchart.
If your content is structured, parsing individual pieces of information, understanding which one is relevant for a particular case, and putting them together is fairly straightforward. I have talked about an application that we’ve built to automatically assemble an entire documentation set from individual reusable pieces of information.
Once the information is automatically assembled, the next step is to dynamically change its representation based on the context or user’s preferences. If you have a short troubleshooting procedure, it could be presented as is, that is as text as it was originally written. If the procedure is complicated and requires different steps depending on the outcome of each check, to make it easier and faster to understand, the troubleshooting can be dynamically transformed from text to a flowchart. Or maybe it can be both.
In this way, we can instantly both assemble troubleshooting procedures for different products from the same collection of reusable individual information pieces and build different representations automatically without having manually to maintain text and flowcharts separately.
One of the applications that we’ve built on our content automation platform transforms troubleshooting procedures to an interactive flowchart.
Suppose we have a troubleshooting topic that contains several possible reasons that may cause the problem and a solution for each reason:
For each check, like checking whether the filter is clean or the draining hose is twisted, there is a separate topic that explains how to perform the check:
Because the content repository includes the information about all product models, only relevant topics should be automatically picked up when assembling them into a troubleshooting procedure for a specific model.
The diagram generated from the automatically assembled topic looks something like this (the styling and colors are easily configured):
If a new product model is released, a new check should be introduced or another change made. It’s only a matter of clicking a button that will re-run the content assembly and the diagram-generation process.
By the way, the application automatically calculates the optimal location of the blocks on the diagram so that the arrows do not cross each other.
In another article, I’ll discuss how a system architecture diagram that depicts system components and interaction between them can be automatically generated out of individual pieces of information.
Following are links to two videos that showcase ideas presented in this article:
https://youtu.be/l2drJxXWdU8 – generating troubleshooting flowcharts from textual troubleshooting topics
https://youtu.be/Z_MHx8M_39A – generating a system architecture diagram from topics and aggregating short descriptions of system components