Well, you are not alone. A proverb “A picture is worth one thousand words” exists for a reason.
Drawing pictures alone never was a problem. There is a 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’re various models of the washing machine that provide different features. A troubleshooting for one model may be 80% 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 differently.
Even if your tool allows you to somehow conditionalize parts of the diagram (a while ago, I managed out 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 and the diagram.
Ideally, troubleshooting documentation that addresses a specific problem occurred in a specific product in a specific context should be assembled automatically and presented to you in a way you want: either as text or 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. In my previous post, I 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 this is a short troubleshooting procedure, it could be presented as is, that is as text as it was written by the technical writer. If the procedure is complicated and assumes different steps depending on the outcome of each check, to make it easier and faster to understand, the troubleshooting could 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 to manually 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 topics looks something like this (the styling and colors are configurable):
Depending on the configuration, the diagram can be clickable so that clicking a check on the diagram will bring up a topic describing how to perform this check.
If a new product model is now released and thus, a new check should be introduced or another change needs to be done, it’s only a matter of clicking a button that will re-run the content assembly and diagram generation process.
By the way, the application automatically calculates the optimal location of blocks on the diagram so that the arrows would not cross over each other.
In the next post, 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. I’m also going to record some videos so you can see it in action.