nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

How does your organization document complex workflows with conditions and functions?

Mike Zdanio

I'm looking for tips and best practices on how to easily document conditions, automations, and functions that are used in workflows in my organization.

We have functions that automatically transition tickets, create sub-tasks or other related work items, set field values, or do other work. We also have restrictions on several transitions to limit them to certain groups or roles.

Is there a better way than tracking them manually in Confluence?

I thought about using the Workflow description, but the max length is too restrictive, and the description doesn't appear to be surfaced anywhere except the Workflow Scheme screen.

Thanks in advance for any tips!

Accepted answers

All comments

Hana Kučerová

Hi @Mike Zdanio ,

some of our customers are using this marketplace app: https://marketplace.atlassian.com/apps/1221996/smart-configuration-documentation-for-jira

Davit Mkrtchyan - Be On Time

Hi Mike @Mike Zdanio -

I have been in this exact position before, and here is the hard truth: any manual documentation of complex workflows in Confluence is a lie. It is outdated the moment you hit Publish.

When a workflow reaches the point where it requires a separate manual to explain the conditions and functions, it is usually a signal that you have a Complexity Tax problem. We often try to solve process discipline issues by adding more technical restrictions - a function here, a validator there - but this just creates a black box that frustrates the team.

Instead of documenting the machine, I recommend focusing on documenting the intent.

First, use a visual tool like Miro or Lucidchart for the high-level flow. Do not document every single function. Instead, document the Business Rule. For example: "Tickets cannot move to QA until the Code Review is approved." It does not matter how Jira does it technically; it matters why it happens.

Second, I would challenge the complexity itself. Ask yourself: if we removed this specific restriction, what is the worst that could happen? Often, we find that we are over-engineering the workflow to prevent a mistake that happens once a year, while making the daily work harder for everyone.

The most sustainable workflows are the ones that are so intuitive they do not need a manual. If you find yourself spending more time documenting the workflow than the team spends using it, it is time to simplify the logic and move the governance to the planning and review level.

Hope this helps you find a way out of the documentation trap!

zoltanersek _outpostlabs_dev_

Out of curiosity, is the primary goal documentation for admins, or helping end users understand what a workflow does?

the best approach depends on the audience

Mike Zdanio

A mix of both, but primarily admins.

Mike Zdanio

I agree with all of this. Unfortunately, I'm trying to untangle some historical complexity, some of which I would like to remove. But I want to start by documenting what's there so I can show leadership what (current) unexplainable roadblocks are there and start removing them to improve everyone's daily processes.

Thanks for the feedback!

Davit Mkrtchyan - Be On Time

@Mike Zdanio That changes the perspective completely. You are not building a manual; you are building a business case for simplification.

In that case, I would suggest a slight shift in how you document this. Instead of a technical description of the functions, create what I call a "Friction Map."

Leadership often ignores "complexity" because it sounds like a technical preference. But they never ignore "friction."

Instead of writing "The workflow has a validator that restricts this transition to Group X," try framing it as: "This step currently creates a 2-day delay because it requires a manual approval from a group that is often overloaded."

When you map the "unexplainable roadblocks" as actual costs in time or productivity, the conversation stops being about Jira settings and starts being about operational efficiency. It is much easier to get a "yes" for removing a roadblock when you can show exactly how much it is slowing down the team.

It is a brave move to untangle historical complexity, but it is the only way to actually scale.

Rooting for you and your team to get that "clean slate"!

John Funk

Hey Mike,

You might try asking Rovo to build a Confluence page for you with the details. Be sure to be as specific as you can be for what you want in the prompt. I have not actually tried to do this before, but it will be interesting to see what it does with it.

Sascha H_

Hi @Mike Zdanio

we do a lot of customizing.

This includes handing over specs from people designing functionality to people implementing it.

We use visio, do full flowcharts of the workflows and add every single screen, condition, validation, automation to the arrows (transitions).

Anything that has more complexity than, e.g. checkMandatoriness(field) or isInRole(role) points to additional prose (docs/ confluence).

Unfortunately it is not exactly easy. But it's reliable and a very good base to address changes.

Cheerio, Sascha

SPHIOR

You clarified further down that the goal is documenting existing complexity to build a case for simplifying it. That changes the answer, and I think it changes it a lot.

For a business case, documentation is the wrong artifact. Nobody approves a simplification project because a diagram was large. They approve it because of numbers.

The three that tend to move people:

Count. How many workflows, schemes, custom fields, screens actually exist, versus how many are in active use. "We have 340 custom fields and 90 of them appear on no screen in any project" is an argument. A flowchart is not.

Churn. How often this stuff changes, and by whom. A workflow edited eleven times in a year by four different admins is evidence of a process that isn't settled, which is a different and more urgent problem than one that's merely complicated.

Blast radius. How many projects break if you touch one shared scheme. That number is what turns "we should clean this up" into "we can't safely change anything", which is the sentence that gets budget.

The first two you can pull from the REST API in an afternoon. The third is harder and mostly manual, but you only need it for the two or three worst offenders to make the point.

Then document the workflows, once you've won the argument — for the ones that survive.

Disclosure: I build a Jira app in this space, so counting config is a professional deformation. Nothing to pitch; the API gets you the first two for free.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira

cloud

jira-cloud

documentation

workflows

workflow-transitions

workflow-conditions