Documenting the process

After identifying a process as a good candidate for automation, a good first step is to walk through it and document it in enough detail. This documentation will then serve as the basis for implementing the software robot that will take over and handle the process in the future.

The initial documentation will not be perfect and does not need to be. You will need to update it when you learn more about the process during implementation.

Document the process in as much detail as you can. During implementation, you will surely find that you have missed some things or need to do things differently. The documentation will need to be updated with the implementation and vice versa.

Change is inevitable. Change is good. Embrace change! You will learn more about the process you are automating during implementation. Be agile.

During this requirements gathering, the software robot developer needs to work closely with the business side to get familiar with the current process and the business domain in which it runs. This often means sitting next to the user when the process is run, asking all relevant questions, and exploring all the possible scenarios.

Continuous communication between everyone involved is needed through the whole project.

Once again: You will definitely miss some details or possible logical decision points, exceptions, or other scenarios. Gather enough information to be confident enough with starting with the implementation.

As your implementation progresses, you will learn and then incorporate those learnings into the documentation. Automation is a long-term team effort, not a one-way waterfall where each "phase" strictly follows the next and where changes are frowned upon.

The Process Definition Document (PDD)

The results of the process walkthrough are collected into a document.

In the most formal form, we call this document the Process Definition Document.

What do we mean by formal regarding the documentation? Some organizations prefer to have very detailed and strict processes for managing documentation. For example, writing down everything in minute detail, reviewed by multiple stakeholders, getting approvals, signing off, change management protocols, etc.

There's nothing wrong with that approach, but a less formal way of managing documentation might be more suitable for many cases.

Still, by describing the more formal way, we also cover all the relevant things. Remember that you can and should adapt the documentation to your needs. Only use what you need and scrap the rest!

Contents of the PDD document

An effective PDD document should provide clear answers to these questions:

• What is the process used for, and what is its end goal?
• What are the steps involved in the process?
• Are there any decision points (logical branches)?
• Who is in charge of the process?
• By whom and how often is the process executed?
• Does the process require human intervention (attended), or can it be entirely handled by automation (unattended)?
• What are the systems involved in the process?
• Does the user need special authorization or roles to run the process?
• What are the possible problems and exceptions that can happen during the procedure? How does the user handle those?

Bonus: Download our process definition document template

For the more formal documentation needs, we are happy to share our process definition document template that you can use freely in your next automation project.

Remember: If you don't need a very detailed and formal document, use something simpler.

Let's write the PDD for Maria's case

Let's see together how a process definition document for Maria's case would look like.

Surprise! We have made the PDD document for you already. You can download it here and follow along:

Process name

First of all, we need to come up with a name to identify the process. The business might have a name for it already.

In our case, we have gone for "Weekly sales report creation", which is what Maria calls it (In public. She has other names for it, especially when she makes a mistake 🤬).

Document metadata

Versioning

You should set up your document so that it is easy to update and archive. If you are not using a versioning system (you really should!), we recommend adding the version in the file name and a table inside the document to show the current and previous versions.

A good option is to store the documentation with the robot code in the same version control repository. That way, the documentation, and the implementation can be found in the same place, and keeping them in sync is easier.

Storing the documentation separately from the implementation is fine if you can ensure that changes to the document or the implementation always go hand-in-hand.

There's nothing more frustrating than:

• Finding out the documentation is out-of-date.
• Not finding the documentation at all (was it in SharePoint, Google Drive, on Bob's computer...?).

Our recommendations:

Store the documentation in the same version control repository with the robot implementation.

When you change the document, also match those changes in the implementation.

Prefer a simple text-based documentation format (instead of something like a Word document). Markdown is a great, easy-to-learn format for written content and works well with version control systems such as Git (it's easy to see what was changed, when, by whom, and even retrieve old versions).

Sign off

In more formal environments, it might be a good idea to sign off the general idea by the business side. That is:

"We the business, and we the developers, as a team working together towards our common cause, agree that our high-level goal is described in this document.".

Worth repeating one more time: There will be changes. Those changes are inevitable. The changes are not evil. They are the byproduct of learning more about the process and the steps to automate it.

Do not sign off to a level where everything has to be exactly as described in the document. This has, and will not, ever work well in any sizeable software project.

Suppose you disallow changes by strict implementation rules that someone has tried to guess perfectly beforehand. In that case, you will probably end up in an endless change management process where the whole project grinds to a halt due to not being able to react to new learnings or surprises that were not planned for in the "perfect" plan.

The software business is people business. You (the people working on the same thing) are a team. Agree on common goals and then do your best, working together, to find the best way to reaching those goals. Yes, it is a trust-based business. You are all professionals. By leveraging and combining your strengths, great things can be achieved!

In our example, we probably will require Maria's sign-off, and since the process has been the same for years, there should not be too many surprises. Marias sign-off does not mean that the plan is perfect. It means you agree that you have enough information and understanding to start working on the project.

Contributors

List the people that have collaborated in creating the document. It will be useful to record the key people on the business side who know about the process also in the future.

In our example, we would list ourselves!

Current process analysis

This section is where you will use your analysis skills to describe how the client is handling the process now before you move in and optimize and automate it like a pro.

• What steps does someone inside the company have to take each time to make this process work?
• How often is the process executed?
• What software do they have to use?
• Where do they get the information they need?
• What happens if something goes wrong (how to resolve the situation, who to notify of failures, what parties does the failure affect)?

All these questions need to be answered in this section.

High level description

Here you should give an overview of the process. What is this process for? How often do they run it? When do they run it? Who runs it? What are the steps?

This overview description should be crystal clear and not too long to read.

Systems involved

Processes that are a good fit to be automated by automation often span across different systems. For example, one could be a web application, another a legacy system, or even just a spreadsheet.

List in this section the systems involved. Don't forget to explain what they are used for and if the user needs particular authorization roles or rights because the robot will probably need to have them as well!

For our example, we will have Microsoft Excel, the Intranet, and Microsoft Word listed here.

Process flow

One of the best ways to show the steps of a process is via a flowchart, a widely used convention when describing procedures and algorithms.

There is a variety of software to easily create flow charts: good options for example are Diagrams.net (free) or Lucidchart (free with paid option), or Microsoft Visio (paid).

Here's how the process flow looks like for our example:

Detailed steps

Here, you will break down the process into steps, and for each one, you will provide all the information needed.

Try to imagine that you are explaining this to someone who knows nothing about the process: after reading your instructions, they should be able to complete the process on their own.

A good name for a step for example is in the format <operator> <action> <object of the action>. For example: "Employee downloads the Excel file". This is not a hard rule though, just make sure that the name clearly and concisely describes the step.

In each step's description, you are free to add anything that you think will help explain it better: screenshots of the user interface, the schema of the data involved, etc.

Possible exceptions

So far, you have described an ideal case where the operator has all the data they need, all systems work perfectly together, and the result is achieved.

This is not always the case: there are times when the process does not run that smoothly or cannot be completed for various reasons: we call these cases "Exceptions".

Exceptions can be of two types:

• Business exceptions: Business exceptions happen when something is wrong with the information being processed. For example, if an order has incomplete data, the operation has to stop. Or maybe the business requires specific rules that the operator knows about: "do not sell more than ten pieces a day for that product". These need to be written down carefully because the robot will have to follow the same rules.

• System exceptions: Software can have bugs, network connections can fail, passwords can no longer be valid: in all these cases, we say that a system exception has happened. Write down all these possible cases, explain what the operator sees, and if there are ways to get around them.

In our example, a business exception happens if Maria types her password wrong, and a system exception is a server error that she reports to see sometimes.