How to go from documents to diagrams

This guide details the benefits and process of converting text-based documentation to documentation in a repository-based solution such as QualiWare that uses objects and diagrams. This document additionally covers suggestions and recommendations that organizations can heed when converting and improving their existing documentation.

First, some suggestions as to where text-based documentation can be gathered will be given. This includes quality management systems, the service catalogue, information system overviews and so on. The typical deficiencies of text-based documentation will then be outlined by presenting an example case along with a step-by-step guide to remedy the deficiencies by converting text-based documentation to object-based diagrams.

Identifying suitable documents

Most organizations already have text-based documentation. Finding appropriate documents within the organization can however be a challenge. Possible sources of existing documentation could for example be the quality management program, the service catalogue or value chain, the configuration management database, a document management system, or intranet.

Different sources cover different parts of the organization. It is important to remember that the different domains in your organization do not exist in a vacuum or a silo. For example, essential insight can be achieved by easily being able to simulate the business process impact of a system going offline. The strength of a repository-based solution is that you can collect all of the information in one place to create a cross-domain understanding of your organization.

Quality Management Program

If a Quality Management Program is present, the program hinges on documenting the processes within the organization with the aim to ensure consistent and controlled operations within the organization. Such documentation typically focuses on processes within the organization, detailing standard operating procedures, workflow execution guidelines and other operational information.
This information can be used to kick-start the transition from documents to diagrams and objects from the bottom-up. Documentation of this nature can be broken down into three parts as detailed below:

Process Description

Documentation that describes what the normal/accepted operating procedure for a process is. This information is used for creating the diagram in a repository-based solution by clearly drawing all of the activities that take place in a specific process.

 This is typically where gaps in the documentation are identified, as placing graphical elements on a diagram can clearly show gaps in logic and contradictions which are much harder to spot in text.

RASCI

Keeping track of the various actors involved in the process is one of the most basic and important things a quality management programs can offer. Unfortunately, in a document format it can be hard to easily discern who is responsible or involved in a particular part of a process without having read the whole document.

Once obtained, RASCI information can be added directly to the process description diagram, to the activities where the actors play a role. This is also typically where gaps in documentation are identified, as in an object repository-based approach, it is relatively effortless to spot when an object is missing an accountable.

Supporting Documentation

There is always a wealth of supporting documentation to be used along with a process description, everything from laws and regulations that must be observed to empty templates that must be used in the process. In textual documentation this information is either referred to by mentioning the supporting documentation or linking to it in text. This presents issues for the reader in that they must put in an extra effort to keep track of all the supporting documentation on their own. Additionally, the person documenting the process has a supplementary workload of remembering and changing all references to supporting documentation when the supporting documentation is updated.

For instance, in QualiWare the reference to the supporting documentation is only created once and a link is established to the single original object. This means that any changes only need to be implemented once and all the references will be updated automatically because they are merely referencing the original object.

Service Catalogue / Supply Chain / Value Chain 

Gathering an overview over the overall activities that the organization delivers both internally and externally is imperative for a high-level overview that the management and leadership of an organization needs. This information is typically contained within a Service Catalogue, Supply Chain or Value Chain.

An overview such as this can contribute with an overall conceptual and even logical structure to the workflows identified via the information from the Quality Management Program.

With a conceptual and logical structure, it is possible to create a break-down “zoom levels” for the diagram-based repository solution. For example, a service called “Provide product” can be broken down to its logical constituents “Purchase raw materials”, “Manufacture”, and “Distribute”. The logical breakdowns can then be linked to their operational breakdowns as gathered from the Quality Management Program.

Information Systems Overview

The organization’s configuration management database (CMDB) is typically a good source of information for the repository. A CMDB is usually used by the IT department to keep track of all applications being used in the organization. Most CMDBs contain information about the applications such as the amount of installations and limited information about the functionality of the IT systems.

In QualiWare, CMDB information can be used as a basis to create application landscape diagrams. Application landscape diagrams can provide your organization with an overview over the dependencies across the individual applications.

 The organization can attain additional benefits such as process/system and system/information dependency by coupling CMDB data with other information from for example the Quality Management Program. Such a coupling can for instance provide the organization with information about which processes cannot be performed if a particular system breaks down or even which process information is stored and managed by which system for EU GDPR purposes.

Example case 

In the example case below, the organization QualiCar, a car rental company, has created text-based documentation for their car rental process. The challenges with a text-based approach will be pointed out and solutions and benefits with an object repository-based approach is presented.

Process Description Document

When we book a car for a customer we typically receive a customer request that we handle until the booking is confirmed.

 When a customer request is received our customer service representative is responsible for creating and placing the booking inquiry ticket.

 It is important that the customer service representative uses a standardized template.

 Once a ticket is submitted a person from financial support takes over and performs a credit rating evaluation of the customer.

 If the customer passes our criteria for credit rating evaluation, then the booking can be confirmed, and the car can be delivered

This is a shortened textbook example of a document-based workflow description. From the outset this form of documentation presents several problems:

• Problem 1:You must read the whole description before you understand the process
• Problem 2:It is not possible to get an overview over the process
• Problem 3:Who confirms the booking if the credit rating evaluation is a success?
• Problem 4:What happens if the customer does not pass the credit rating evaluation?
• Problem 5:What happens after the car has been rented out?

These problems can be remedied by using objects and diagrams to describe the process instead. In the following section the preceding text-based documentation will be converted into the following workflow diagram:

If the customer passes our criteria for credit rating evaluation, then the booking can be confirmed, and the car can be delivered.

Process Description Document

Events

Roles 

Activities

Decisions

Supporting Documentation

Other Workflows

When we book a car for a customer we typically receive a customer request that we handle until the booking is confirmed.

When a customer request is received our customer service representative is responsible for creating and placing the booking inquiry ticket.

It is important that the customer service representative uses a standardized template.

 Once a ticket is submitted a person from financial support takes over and performs a credit rating evaluation of the customer.

The first step in converting text-based documentation into a diagram is to identify key elements in the text that can be converted into objects on a diagram.

The first task at hand is to identify the triggering events for this particular workflow. In this case the workflow is triggered when a “Customer request is received” and ends when a “Booking is confirmed”.

Next, the stakeholders or “roles” involved in this process must be identified. In this case two stakeholders are mentioned: “Customer Service Representative” and “Financial Support”. They are represented as “lanes” for the activities in this workflow. 

Activities are then identified and placed inside the swim lanes. In this case three activities could be identified from the text: “creating and placing the booking inquiry ticket”, “performs a credit rating”, “booking can be confirmed”. When documenting activities in an object-based solution it is necessary to name them as an imperative. Thus “creating and placing the booking inquiry ticket” becomes “Create and place booking inquiry ticket”, “performs a credit rating” becomes “Perform credit rating”, and “booking can be confirmed” becomes “Confirm booking”.

The text-based documentation contained an “if” statement. This is a sign that there is a condition-based decision in this workflow. In this case it is the condition “If the customer passes our criteria” immediately after the activity “Perform credit rating”. Because the object-based approach provides us with the ability of providing a context for the reader, naming the workflow condition “OK?” is enough, as it relates to the activity immediately prior the workflow condition.

On the subject of providing context, context is provided in object/diagram-based solutions via arrows that document the sequence.

With an object- and diagram-based solution it is possible to link directly to any supporting documentation to be used in the workflow. In this case the customer service representative must use a standardized template when creating and placing the booking inquiry ticket. The standardized template can be added directly to the activity where it is to be used for ease of use for the reader.

The text-based documentation additionally mentions that after this workflow, the car “the car can be delivered” via a different workflow. Here again the object and diagram-based approach confers the ability to create a context by linking to the workflow that follows immediately after the booking has been confirmed.

Additionally, it is clear that with an object- and diagram-based approach that there is a lack of documentation for what occurs when the customer fails a credit rating. This is where there is a necessity for discovering additional information regarding this workflow. In this case the assumption is that this triggers a prepayment workflow so that the customer is not lost yet the inherent risks are covered.

This concludes the step-by-step walkthrough of converting text-based documentation of a workflow to a diagram with objects with the abovementioned problems have been solved in the following ways:

• Problem 1: The documentation can easily be understood at a glance by looking at the diagram. What took several minutes in the text-based solution, takes merely seconds when using a diagram.

• Problem 2: By just looking at the diagram it is possible to see all the involved parties, how complex the process is and all the involved steps.

• Problem 3: By utilizing the swim lane approach it is possible to easily see which actor is responsible for what activity in the workflow. It is now evident that it is the customer service representative who confirms the booking.

• Problem 4: Because the process was converted into a diagram it is now evident that the text-based documentation was missing what happens if the customer does not pass the credit rating evaluation. If the process had been modeled as a diagram from the beginning, this oversight would have been noticed in the documentation process. As it is now it is necessary to gather additional information to complete the documentation.

• Problem 5: By utilizing the possibilities present in a repository-based solution it is possible to connect diagrams to each other to create context and workflow links in the documentation. This shows that after the booking has been confirmed, the car is delivered in a different workflow.

Not only was the process documented, but the process documentation was improved through identifying gaps and improving the usability by making supporting documentation easily available and documenting the context.

Follow Us