Development of documentation for production automation systems and business processes
Dennis CraneBusiness process automation systems (BPA) are software and hardware solutions that automate routine tasks, improve coordination between employees and departments, and control task completion.
For example, a Business Process Automation system can help an enterprise in order processing, report creation, and personnel management. It also helps to control processes, increases transparency of operations and solves many other tasks.
However, due to the complexity of the enterprise structure itself, it is not easy, but vital, to train employees to use BPA.
Let's take a closer look at the benefits of creating and maintaining up-to-date user documentation for such programs.
Quick adaptation
A detailed help base with video, graphs, tables and images will help you understand the system much faster without the need to contact technical support.
When users have access to detailed instructions and manuals, they can learn the basic functions of the system on their own without taking training courses or asking for help fr om colleagues. This is especially important in times of high employee turnover and rapid company growth, when new employees need to be onboarded as quickly as possible.
Increased user satisfaction
A process automation system without clear instructions will become a challenge rather than a help. Employees will be forced to spend time on learning how software works instead of performing their tasks. In this case, it is impossible to talk about the growth of their work efficiency.
Standardization of actions
Documentation establishes uniform standards for performing tasks within an organization. All employees will follow the same procedures, leading to consistency and improved results. This is important in large companies with an extensive structure, wh ere different departments may have different approaches to performing the same operations.
Scaling the business
When a business expands or introduces new functions into the system, up-to-date documentation will allow new employees and partners to quickly adapt to the changes. This speeds up the integration of new business units and reduces the risks associated with lack of system knowledge.
Knowledge accumulation
Documentation serves as a reliable repository of knowledge about a company's management system — an important aspect for maintaining sustainability and efficiency. Retaining data on a company's internal processes is useful for analyzing trends, identifying patterns, and making informed decisions. In addition, many industries and jurisdictions require data retention over a period of time for auditing and regulatory compliance.
Business continuity
When the system is updated or personnel changes, the documentation maintains continuity. For example, in case of emergencies or key personnel changes, the reference database will provide the necessary body of knowledge to continue operations.
Fast navigation
Even inexperienced employees can quickly find the information they need in a well-structured document. A well-thought-out, logical structure of the handbook plays a key role in learning.
It may seem that high-quality user manual is not a critical factor in the success of an automation project: the developer has taken care of an intuitive interface, and most employees have a high level of technical literacy and have been working with various software for several years. Many companies work with a small reference document written in an ordinary text editor, hoping that such a reference base is sufficient for quick mastering of the BPA-system.
However, this is far from being the case.
Difficulties in writing user manual for production and business process automation systems
To cover the whole functionality of the BPA-system and describe it in detail is a large-scale and time-consuming task, but it is not only the impressive list of program functions that is difficult. Let's consider the points that the author of the help should pay attention to.
A lot of interconnected components
The complexity of describing the work of components lies not so much in their number as in how to explain their interconnectedness visually. The reader should see the whole picture of the company's management system and understand how a single cog of the mechanism helps to achieve the overall goal. It is necessary to convey to the reader the essence: the constituent parts of the BPA-system are not disparate parts, dependent on each other components.
Without the use of schemes and media files, it will not be possible to unravel the tangle and convey the principles of interaction between the elements. The author himself should be able to think figuratively and understand very well the internal structure of such systems.
Complex terminology
If an experienced employee is well-versed in terminology, a newcomer will quickly get confused by unfamiliar names and formulations. The technical writer must find a balance at which the text is understandable not only to the expert, but also to the inexperienced employee. At the same time, the instruction should be written in such a way that it does not look like a constant repeating of obvious things, and should be written according to the principle “from simple to complex”.
Regular update
Constant updating is a feature of any software. This imposes additional responsibilities on the author of user help, who has to keep track of changes and keep the content up to date. Just like a soft developer, he or she needs to be familiar with text versioning systems. Fortunately, specialized programs for writing user help for BPM systems (Business Process Management) have built-in tools for this purpose, which makes the work much easier. Text editors such as Word are not suitable for this purpose.
Recommendations when creating user documentation for production and business process automation systems
Relevance
Documentation should be upd ated regularly to reflect changes in the system. This is obvious, but many authors don't pay enough attention to it. We wrote about what happens if you don't maintain and update data in this article “Applying Broken Windows Theory to Writing Documentation”.
Accessibility
Documentation should be accessible to all users. It is difficult to write text that is equally understandable to employees of different departments, but the above-mentioned visualization tools come to the rescue: video clips, tables, schemes. Here we come back to the fact that in order to create such visual instructions you should use specialized software for writing user guides.
Clarity and simplicity
Information should be presented in clear and accessible language, without excessive technical terminology. These recommendations apply to any text, but in the context of an organization's work, they have a direct impact on numerical indicators.
Structuring
Documentation should be well structured, logical and have a convenient navigation system. A/B testing can be used to create the most convenient arrangement of sections, menu items.
Illustrations
The use of schemes, diagrams and other visual elements makes it easier to understand complex processes. It makes sense to design media materials in a unified style, so as not to turn the document into a colorful mishmash. The familiar text editor Word (and similar programs) offers a very limited se t of tools for customization.
Examples of user documentation for production and business process automation systems
Learn from other people's examples. You can borrow a lot of interesting things from well-known companies when creating user manuals for business process automation systems. Let's consider some of them.
Cflow
Everything in the user documentation of the cloud service Cflow is standard, the only thing of interest for our topic is the glossary, which is placed in a separate section. On its page, terms with a brief description are located in alphabetical order.
If you are not yet familiar with cloud-based services (SaaS) and how they differ from desktop applications, read about it in our article.
Bizagi
In the user documentation of Bizagi service, step-by-step instructions are accompanied by the corresponding image, which makes it easier to digest the information. In addition, each step has a link to the corresponding topic of the help base.
There is also an “In this article” button on the page for easy navigation through the page:
Developers explain complicated things with lots of images:
IBM Cloud Paks
The IBM Cloud Paks service has command line capability, and the documentation demonstrates this very well: with a click of a button, you can copy a piece of code without having to type it manually. In the upper right corner there is a button to switch to a dark theme to reduce eye strain. On the left, there is an option to “Show full table of content” and switch between documentation for different versions of the program.
Process Maker
For some users, the design of Process Maker documentation may seem excessive: there's an article rating, a navigation menu on the right, fonts of different thicknesses, different families, different sizes, and horizontal content dividers:
Perhaps such a design came to it as a result of working with feedback, and it makes sense. How useful a particular design is to users can be found out through A/B testing.
Comind Ware
The help base of the Comind Ware low-code platform greets the user with a small menu, from which you can go to the appropriate topic. Breaking down the documentation into such modules makes it much easier to navigate through the help.
Camunda
The Camunda developers have emphasized ease of navigation and added relevant shortcuts directly to the documentation page:
An Edit this page link has been added at the end of the page, leading to Github, so that users can participate in creating the documentation:
Nintex Automation Cloud
Nintex Automation Cloud use many annotated screenshots of the interface:
Kisflow
The Kisflow platform has added short videos to its manual:
Dr.Explain — a tool that speeds up creation of user documentation for BPA systems
We have already mentioned that professional user help base for BPA-systems should be written in special software. One of them is Dr.Explain software, which speeds up the creation of any reference manuals. With its help you can work on projects of any complexity and export them to the most popular formats. Here are some features of the program.
Ready-made documentation templates with a pre-organized structure
After installing Dr.Explain, you can select one of three project types and start adding content to pre-prepared topics.
Standard text block templates
A se t of standard text block templates extends the possibilities of visual design, stylization of different types of content:
Easily export documentation to HTML, PDF, Word, CHM
Once you have written a reference manual once, you export it to any of the common formats. When exporting, you can customize the output of certain parts of the content. Suppose you want a document that explains the command line for one group of users and a version of the document that does not explain the command line for another group of users. By specifying options in the export settings, you will get different versions of the same project.
Work of a distributed group of authors
The possibility of remote work on one project by several authors at once is becoming more and more popular. This is implemented in Dr.Explain with the help of TiWri service.
Easy navigation in help documentation of any size
Awkward navigation is a common problem with user help documents, especially if they are written in Word and similar text editors. They are not designed for complex projects, so users get lost in them and the learning process is delayed. Specialized tools for writing reference documentation like Dr.Explain are easy to navigate.
For example, Dr.Explain creates keyword indexes. A phrase or word is attached to specific pages of the help file. The indexed list helps you find the information you need quickly.
Conclusion
BPA systems solve many tasks and speed up work, but only if users do not have to contact technical support every second. If automation makes business processes easier and more efficient, then user mnual for BPA systems makes it just as easy and efficient for employees to work with the system. These are two interrelated things that must necessarily complement each other.
As they say, a good tool does half the job. In the case of creating help for BPA and business process management systems, this is indeed true, because by installing a specialized program for the help base, such as Dr.Explain, you get a ready-made structure for your future project. We have described an example of the features that a software for creating high-quality help can have above. An ordinary text editor can hardly boast such features, and the fewer tools there are to explain complex and confusing concepts, the harder it is to convey information to the reader.
To sum up, we can say that it is not easy to organize a project containing comprehensive information about the operation of a complex and multilevel structure, such as the BPA-system, but if you know what tool to use, you can simplify the task greatly.