> When has JIRA actually been effective as the documentation for a bugfix?

We use JIRA specifically for this. Commit messages are JIRA ticket numbers and a short message to provide some context.

In JIRA we document what was requested/reported and which customer the issue affects/came from. We attach relevant documents and link it to possible related tickets. If a case is unclear we send it back to support and get additional info.

Once we commit we comment if needed to provide additional details. Our build pipeline then updates the ticket with build numbers after the issue is resolved so we know which versions has the build, which is pulled by our update distribution mechanism.

This way customers will get a notification when a new version is available that has a fix for one of their issues.

We then assign it to someone on support so they can follow up with the customer and verify that the issue is resolved, or we get the issue back with more details.

This way it's easy for both support, devs and management to see what's going on, and it has the needed context in case someone else has to take over.

Not saying JIRA is perfect by any means, but this works quite well for us. I should mention though that we use on-premise install so speed is not an issue for us. By the sound of things we'll be finding some alternative once that option is gone...

I have absolutely seen documentation in Jira. Sometimes the canonical advice for how to do a task is "Go clone JIRA-1234 and follow the steps laid out there".

It's a shitty documentation system because it's extremely hard to find that organically, but people do use Jira as documentation.

I've definitely used issue tracking systems to look into why a bug was fixed a particular way - if a fix is non-intuitive, including the issue # in the commit messages can give you a lot more context than just a commit message.

I’ve seen Jira be the source of truth for user stories related to changes. It was neat at first because you could track why something was changed and what it was supposed to do, and even have a user confirm it’s working the way they expected (I hate when bugs are closed because the dev thinks it’s fixed but it actually isn’t). The ticket would point to source or git log if you wanted more detail.

Sadly it developed from a tiny, quick, useful note to a documentation slog when a new project manager joined and wanted a long description of everything typed into the ticket. So I ended up killing Jira altogether.

Wouldn’t it have been easier to explain to the project manager that there were costs associated with documenting the minutiae, get them onboard and continue to use the system that has worked for you? (Genuine question, not a rhetorical one)

I thought so, but I wasn’t successful. I’m not sure how much was just someone new trying to change stuff and someone who really believes in writing tons of stuff.

I don’t think the problem was jira, it’s just in project management thinking that it is the most important part and the dev work is subservient or easy.

We have an automated process where emails to our support distro go to JIRA and Slack via Zapier. No user request or bug report gets lost. Issues with insufficient info get followed up on by an ops/support person. All feedback and actions go into the ticket. Something that can be worked around is documented and resolved. True bugs get logged to the dev backlog and linked to the support ticket. Works like a charm. The users can see the ticket history without really learning much about JIRA. Devs in know exactly how the issue was reported and triaged. Probably 3/4 of issues are resolved without a dev ever being roped in. And no user ever wonders what happened to their request.