👤 For process owners and pipe administrators
🔐 Practices apply to all plans; access to specific features depends on company permissions and subscription
🎯 For people preparing a process for changes or a handover
Someone needs to change a purchasing approval criterion, but the explanation is scattered across old messages and the memory of the person who built the workflow. Before assessing the change, the team has to find out which information supports the decision and who needs to review it.
By the end of this article, you will know what to record about a process, where to keep that information and how to use it to plan maintenance. The goal is to help another person understand the pipe and find the dependencies they need to check before making a change.
📖 What you will understand here:
What useful process documentation needs to explain
Useful documentation answers two questions: how the process works and why it was designed that way. A list of phases shows the route, but someone taking over maintenance also needs to understand what determines the decisions along it.
Start with the purpose, the entry point and the outcome that completes the work. Identify the role that owns the process and the decisions that require their involvement. If the workflow continues in another pipe, record where each team's responsibility ends.
In a hypothetical purchasing process, the scope might run from receiving a request to approving or canceling it. Payment execution might belong to a separate process. Making that boundary explicit helps people assess a change without taking on another team's responsibilities.
A request's history and process documentation serve different purposes. The history helps explain an individual case; process documentation explains the logic that should guide cases in that process.
Where to keep process information
Make the final process documentation identifiable from the pipe description. This is the reference point for someone who needs to understand the workflow's purpose and find its owner.
Use the description to record the purpose, a summary of what happens across the phases and the role responsible for the process. Keep guidance for individual steps in the phase descriptions. When rules and dependencies need more detail, maintain a supporting document and indicate where to find it in the pipe description.
Choose one main reference for the detailed information and check that the people maintaining the process can access it. Include the latest review date so the team knows when that version was checked.
To compare the documentation with the current configuration, administrators can use the Flow view. It brings together the pipe's phases, fields and automations. Business decisions and external dependencies still need their own explanation.
- Learn more: see how to review the process structure in Flow in this Portuguese Help Center article.
How to describe the work in each phase
For each phase, combine the agreed turnaround time, the responsible role and a short explanation of the expected work. Add the criterion for moving forward and the route for cases that need corrections.
In the purchasing example, an Awaiting approval phase could say: “Responsible role: requesting department manager. Agreed turnaround time: two business days. Review the justification and requested amount. Record the decision before proceeding. If information is missing, send the request to Corrections pending through the designated process route.” The timing and roles are illustrative and should reflect the company's agreement.
Writing a deadline in a description does not configure an SLA alert. Naming a responsible role does not automatically assign cards either. The written guidance and the configuration need to reflect the same agreement.
Use the same phase names in the documentation and the pipe so people can recognize each step. If colors represent responsibility in your process, explain that convention too. Explore these criteria in best practices for organizing and naming phases, available in Portuguese.
How to connect rules and fields to dependencies
Before documenting a rule, explain the business decision it represents. Then identify the scenario that triggers it, the conditions evaluated, the expected action and the fields or destinations involved.
For purchasing approvals, record where the amount comes from, which current criterion determines approval and who can authorize a change to that criterion. Indicate where to find the corresponding configuration. The next review can then connect the rule's purpose with the elements that need checking.
Use consistent names. An automation name should identify the trigger phase, scenario, condition when needed and action. A conditional rule's name should help people recognize whether it shows or hides a field and under which circumstances. A conditional rule controls visibility; an automation performs an action in response to an event. Document their roles separately.
For fields used by rules, record the purpose, source of information and dependencies. Include the technical identifier when the person maintaining an integration needs it. This is particularly useful for hidden or auxiliary fields whose purpose may not be apparent during everyday work.
When using [Auxiliary], [Integration] or [Inactive] prefixes, explain in the field description why the field exists and what depends on it. Keep a “Do not delete” instruction when preservation is necessary. The note communicates a precaution; it does not technically prevent deletion.
Also document correction loops: who receives the card, which information must be preserved before clearing fields and how work returns to the main route. For approvals and other critical transitions, record which mechanism controls movement and which conditions must be met before triggering it.
What to record about connections and participants
When a process connects to other pipes, databases or systems, record the data source and destination, the purpose of the exchange and who maintains each part. Include where to find the connection settings and which team should participate in a change.
If an integration uses a service account, identify the account by reference and name its owner. Plan to review older connections when responsibility or systems change. Keep passwords and tokens in the secure location defined by the company, outside the process documentation.
If the process uses AI Agents, document their context, input data, action and expected output. Record how responsibilities are divided between agents and people, including who reviews exceptions under the company's process.
Complete the record with participation channels: who works in the pipe, who responds through a form or Interface and who can maintain the process. For email communications, identify the templates involved and their purpose. For timing rules, record the time zone reference used.
You do not need to add features to fill out the documentation. Record the dependencies that exist and explain what the company needs to preserve when something changes.
How to update documentation after a change
Agree on who reviews the record and which changes require an update. Changes to phases, fields, approval criteria, connections, ownership, access channels and deadlines are useful moments to check whether the documentation still reflects the process.
Keep a short record of the date, change, reason, dependencies checked, reviewer and test performed. In the purchasing example, changing the approval criterion means reviewing the rule's explanation and the elements that use that criterion, as well as the corresponding configuration.
Include a case that moves forward and another that returns for corrections in your test, when those routes exist. Update affected screenshots or diagrams too. To check clarity, ask another person to use the documentation to find the rule and explain the impact of the change.
To explore the relationship between mapping, responsibilities and implementation, continue with the Process Implementation Certification at Pipefy Academy. This course page is in Portuguese. Access to lessons requires an account or sign in.
Where to start with your process
Choose a pipe already in operation and a change your team expects to make. Use these questions to organize the first version of the documentation:
- What is the process for, where does it start and when does it end?
- Who owns the process and who maintains it?
- What should each phase receive and deliver, with which owner and deadline?
- Which rules, fields and connections support the decision being changed?
- What happens during corrections and exceptions?
- When was the record reviewed and how was the process checked?
Start with the pipe description, complete one phase description and document one relevant rule in detail. Expand the record as further maintenance takes place. The measure of quality is whether people can find the information they need to assess a change with context.
Before moving on, confirm that you understand:
☐ The pipe description explains the process purpose and owner and points to the detailed information.
☐ Phase descriptions explain the work, while separate settings define assignments and alerts.
☐ A change requires checking related rules and dependencies and updating the documentation.
☐ Another person can find a rule and explain what needs reviewing before changing it.
Ready to prepare your next change? → Review the current process structure in Flow and compare it with your documentation. The linked guide is in Portuguese.
