How do you "document" your workflows?

Does anyone have any good examples or ideas on how to document workflows, other than the obvious built-in workflow diagrams?

We've got a number of systems we've inherited. I'm trying to wrap my head around a good clean, understandable way to present the various pieces of data in a "workflow" in a human digestible form.

Things like state x to state y uses transition z which has conditions, validations, and post-functions.

We often get tripped up by the non-obvious things, like conditions and validations and spend a fair amount of time explaining to users, as well as admins, why Bob can't move from Ready to Integrate. We end up digging into the workflow config to find out which role can do what.

I'm struggling with how to present it as simply as possible for humans to look at, and figured I can't be the only one who's struggled with this. Surely someone has similar documentation they use?

1 answer

Is the doc aimed a JIRA users or admins? If it's for users I'd like a plugin that show unavailable transitions and why they are like that. For admins a big ol spreadsheet generated from workflow XML would be more useful. I think I've heard of that being done?

Largely for admins, but if I can find a format to convey the information in a clean enough fashion, users would benefit. I don't know about others, but I find it tedious to get reports from users of "I can't move issue to state, I used to". I end up digging into the specific workflow, often to find out there's a condition stopping it from happening. I'd like some form of matrix or diagram (though I think it's too much data to present on a diagram) to help more quickly debug these scenarios. I'd also like something the admin team can look at to help more easily assess the impact of making a change. Another, very real example, is that we're currently in the process of deprecating some old custom-built plugins that we've inherited. We have enough workflows, and places for these plugins to be present, that it's fairly tedious to wade through XML or screen by screen to find them. While better documentation won't help me this time, if I had it, this would be far less painful. I'd love a way to auto-extract the information and then clean it up by removing all the behind the scenes post-actions etc, leaving just the relevant bits.

Suggest an answer

Log in or Sign up to answer
Community showcase
Published Jan 08, 2019 in Jira

How to Jira for designers

I’m a designer on the Jira team. For a long time, I’ve fielded questions from other designers about how they should be using Jira Software with their design team. I’ve also heard feedback from other ...

1,234 views 5 10
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you