How do you "document" your workflows?

Question

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?

Mark Montminy2 · Answer

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.

MattS · 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?