Suppose you are part of a documentation team that documents a complex product. The product consists of multiple components, and each component is assigned to a certain technical writer or a group of writers.
Each writer knows everything about the components assigned to her and has a general knowledge about other components. Someone (perhaps, a team lead) needs to put individual pieces of information written by different writers together and describe how the system works as a whole. At this point, the team lead needs to write an overview that at the very least includes a system diagram and a brief description of the components depicted on the diagram.
As long as the diagram is created just once without any need for updates, it’s not a problem. The problem arises when this diagram needs to be updated after a component is changed, a new component is introduced, or maybe after an existing component became obsolete. Or when there are multiple flavors of the product, and each flavor includes a slightly different set of components, or in each product flavor, the components interact differently.
In this case, re-drawing the diagram or creating multiple variations of the diagram might become a nightmare.
We’ve built an application for our content automation platform to address this challenge. The application searches in the content repository for pieces of information required for a specific product, automatically generates a system diagram which shows how major components interact with each other, automatically creates a table with a brief description of each component, and automatically creates a topic which includes the diagram and the table.
When something changes in the components, you just need to re-run the generation process.
To help you get a general idea of how it works, let’s say you need to document a system that automatically recognizes pair socks after laundry. The system consists of several components:
For the sake of simplicity, let’s assume that each component is assigned to an individual writer. The writer documents the component as usual, and is expected to do two just two additional things:
If a component interacts with other components differently in different product versions or flavors, several possible inputs or outputs can be added and profiled. Then inputs and outputs irrelevant for a particular product will be just filtered out, and the diagram will be generated accordingly.
The application finds the topics required for a specific product based on metadata, retrieves the text from <shortdesc> (or any other element used for the short description), generates the system architecture diagram based on the input/output tables, and puts the diagram followed by the table with short component descriptions into an overview topic.
Click here to see an HTML output of the automatically assembled topic (the text in the beginning of the topic and between the image and table is coming from the template).
It’s just an example of what can be done. Everything is configurable. For example, the image can be generated as SVG, it can be clickable (that is clicking on a component will bring you to the topic that describes this component), the look-and-feel of the diagram blocks and arrows can be changed, the components can be re-arranged, and so on.
The next two post will be actually videos that show this application and the one which generates a diagram from a troubleshooting topic, in action.
Stay with us!