Jira workflows - agile - steps, statuses or something else?

Craig Wright2

Hello. I'm a complete noob to creating workflows (in Jira or elsewhere) and am growing increasingly confused by the jira documentation, videos, etc., online. Hopefully, someone out there can help get me back on track.

I need to create a workflow for creating documentation (Confluence). I have the process of what the writer needs to do and what the reviewers/approvers need to do all planned out. The problem is that I can't figure out how to translate that into a jira work space.

For example, let's say we go from Open to Assign to Writer to Create Content (Create Content consists of plan, research, write) and then on to review. Should there be a separate status for plan, research and write, or should there just be a Create Content status that is associated with In Progress (and the steps within Create Content not mentioned at all)?

Any advice is much appreciated.

Nic Brough -Adaptavist-

I'd break this down a bit.

First, I'd take your last paragraph - before trying to create a Jira workflow, map out what you want in the real world. I generally scribble out a simple flow chart, which lends itself to Jira workflows anyway - each circle is a status and each line between circles becomes a transition.

When you're deciding what status you want to flow through, you need to bear in mind your reporting and how each team is going to work. I usually think of two things at this point for each status. The first one is about what the process really is from a user's point of view. In your case, you decide something needs writing and create an issue for it (status Open) - that's easy. But the next step is less obvious. You want to assign it to a writer. The question here is down to whether you're happy to simply assign it to the writer and leave it "open" so the writer knows it's in their queue, or you actually need to know that it's no longer "open" and has moved a step forward - if that's the case, you need a status like "in writers queue". Either way, the next step is easier - decide whether the writer should just go straight to "I've done it, give to reviewer" or they should have an "in progress" status, and then when they've finished writing, say "I've done it, give to reviewer". You then need to make the same decisions from a reviewer point of view - do they need waiting/in progress/complete, or just waiting/complete.

Before you jump one way or the other though, think about your reporting. How do you want the question "what is happening in the queues" - is it useful to know something like 10 open, 20 assigned to writers but not started, 5 being written, 17 waiting for review, 4 under review and 92 complete? Or the more simple, 35 open, 21 in review and 92 complete?

The second thing I think about is a lot easier - the names of status. You need something indicative of what is happening with the issue, and the easiest way to do it is make your status names fit the pattern "This issue is <status>" - if the sentence formed by that is clear, you have a good status name.

Next, you convert your lines to transitions - again this can be quite straightforward, but people often forget to account for non-ideal flow. Think about re-opening items and if things fail reviews. You'll always want at least one transition out of every status to avoid dead-ends. Think about using conditions to control who can do what (e.g. reviewers can't move things into review, and writers can't sign off on reviews)

As for naming transitions, try to think of them as action/verb words. Again, wedge it into a sentence - "I want to <transtion> this issue"

Finally, a quick note on steps and status - steps are a skeleton to hang a workflow off. Users won't see them. I try to keep the step names the same as the status they are for, but don't worry too much about it - status names matter, step names don't.