From Documents to Diagrams

Text based documentation has drawbacks. See why object/diagram-based documentation has advantages

Home Blog From Documents to Diagrams

Text-based documentation has five main drawbacks such as (1) the inability to easily get an overview over the particular piece of documentation, (2) the inability to easily understand the individual piece of documentation in a context, (3) the fragmented nature of the documentation often taking the form of several different types of documents distributed throughout many locations in the organization, (4) it is cumbersome to maintain, and (5) the inability to execute analyses on textual data.

In this blog post, I will detail how an object/diagram-based solution like QualiWare can remedy the aforementioned drawbacks:

Drawback 1: Lack of overview

Text-based documents take time to read and often you must read the whole document before a comprehensive understanding of the content can be attained. It is for example impossible to at a glance extract information regarding all of the involved stakeholders from a wall of text. The whole text must be thoroughly, if not read, then skimmed.

When the text-based document takes the form of a diagram all information that was previously hidden in the text takes the form of a graphical element on the diagram.

For example, any stakeholders who would be involved in the workflow would be easily identifiable via their unique icon/shape on the diagram. Likewise, an individual stakeholder can get a quick overview over all of the tasks they must perform and their sequence without needing to read the whole text.

Drawback 2: Lack of context

If a document were to contain enough complexity to adequately cover the context that the documentation exists in, the document would be too large to understand. With text-based documentation there is an eternal battle between including too much and too little information.

With an object/diagram-based solution such as QualiWare the context is dynamic. QualiWare contains all of the information in its repository and it is up to the users to add/remove complexity as they see fit.

For example, the diagram could be broken down into smaller chunks that link to each other as in the example in the picture where the first diagram details the first logical chunk of a workflow “Book car” and then at the end links to the continuation “Deliver car”.

Drawback 3: Fragmentation

Document-based information is fragmented in nature. It can take the form of for example a word document, excel spreadsheet, PowerPoint presentation, or even a Visio drawing. Each piece of documentation can then be located either locally on an employee’s personal machine or in an obscure folder on a shared drive in the organization. These circumstances contribute to making it more difficult to find the needed documentation, when it is needed. Additionally, because the individual pieces of the documentation are not connected to each other, contradictory information might be contained within them.

In QualiWare all documented information is stored centrally in a repository. This ensures that there is a single source of truth that people in the organization need to consult instead of having to scramble for bits and pieces of the truth. Accumulating all documentation information in a single location confers the added benefit of enabling the identification of gaps in the documentation. This is because if the information is not in the repository, then it is lacking.

Drawback 4: Cumbersome maintenance

Tracking changes in text-based documentation is very cumbersome because of the nature of text. If for example a common procedure were updated it would be decidedly inconvenient to first identify all the documents that referred to that particular procedure and then it would take a lot of time to re-write the individual sections where references were present.

QualiWare solves this issue by breaking the pieces of information down and consolidating them into objects. The original objects are then referenced wherever they are needed in the documentation. For example, a standard invoicing activity can take place in several different workflows across the organization. Instead of creating copies of the invoicing process and pasting it wherever relevant, a reference is made to the original invoicing process activity. If the standard invoicing activity changes, the change only needs to be implemented just once to the original activity before it percolates to wherever it is referenced.

Drawback 5: Inability to analyze

Documentation should be much more than just a description of how the organization functions. Text-based documentation lacks the ability to be dynamically analyzed. This means that if you were to create for example a what-if analysis, it would have to be written manually based on the existing information in the documentation.

Objects and diagrams can easily be analyzed since all the data relevant to a particular object is contained within the object and any links between the objects are documented explicitly via graphical relations. These factors not only make the documentation easy to read for humans but more importantly for computers. For instance, in QualiWare it is possible to dynamically generate all the touchpoints between a system and the business processes that use that system in seconds – a task that when done by hand takes hours or even days.

Conclusion

With the drawbacks and their solutions outlined it is clear that repository-based documentation that uses objects and diagrams is far superior to simple text-based documentation.
What’s the catch? There is no catch! Converting your text-based documentation is easy.

Give it a try by following our handy guide