How to document Jira workflows with AI (step-by-step)

Step by step

Pick one path through the workflow

Choose the path people ask about most, for example To Do → In Progress → In Review → Done for a bug. Open the work item and select View workflow from the Status menu to see the statuses and transitions you'll document.

Use a test work item

Create a work item named 'Guide test – do not work on'. Moving real work items for a recording sends notifications and pollutes reports. Delete or close the test item afterwards.

Start recording in Guidie

With the Jira tab open, click the Guidie extension and press Start. Guidie only records this tab, and only from now on.

Create the work item the way your team does

Click Create, choose the space and work type, fill the fields your team requires and submit. Guidie records each field by its label, never the text you type, so summaries and descriptions stay out of the guide.

Move it through each status

Open the work item and pick the next status from the Status menu, or drag the card to the next column on the board. If a transition screen asks for a field (such as Resolution), fill it; that step is exactly what people get stuck on.

Stop and review the AI draft

Press Stop. Guidie writes one instruction per step with the field or button name in bold, plus tips. Add one tip by hand where your site differs from defaults, for example 'You can only move to Done from In Review.'

Share it where Jira users look

Link the guide from your space's summary or your team's wiki page. Render the narrated video for onboarding new team members.

Jira workflows worth documenting first

Moving a work item when the status won't change

Usually a missing permission or a required field on the transition screen. Document what to fill and who to ask.

Logging a bug with the right fields

Which work type, which components, what goes in the description. Saves triage time.

Using the board vs the work item view

Board columns map to statuses set by an admin. Show both ways, since new users only discover one.

Changing status with the keyboard

Power users can open the command palette (Cmd+K or Ctrl+K) and search for Change status. Worth a short guide for heavy users.

Why Jira needs your own documentation

Jira is a framework more than a product: admins define statuses, transitions, required fields, screens and board columns. Two teams in the same company can have completely different flows. A tutorial from the internet shows a Jira, not your Jira.

That's why the most useful Jira guide is short and specific: "how a bug moves from reported to done here", recorded in your own site.

What to capture, and what to skip

Capture the transition screens and required fields. They are where people get stuck.
Capture both the board and the work item view if your team uses both.
Skip admin configuration in user guides. Workflow editing belongs in a separate admin guide with a different audience.

Keep it current

Jira workflows change when processes change. Add the guide's link to the workflow's description or your space page, and re-record whenever an admin adds a status. With a recorder, that's a few minutes.

Questions people ask

Why can't I move a Jira work item to a column?

You need space permission to move it to the status that column is mapped to, and the workflow must allow that transition from the current status. Required fields on a transition screen can also block it.

Does Guidie record what I type into Jira fields?

No. Typed text is never sent; Guidie records which field you used, by its label, and masks the field in screenshots.

Should I document company-managed and team-managed spaces separately?

Yes, if your site has both. Their workflows and settings are configured differently, so screens and options differ.

How to document Jira workflows with AI