> 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.

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.

It's just so obviously an absurd statement to say that if a bug is fixed and not documented meticulously in JIRA it is as useless as if it was never fixed at all. A huge portion of the day to day work of software engineering happens without explicit documentation of every decision for every change for every line of code. Life continues, software is built.

The necessity for documentation exists along a spectrum, and the means of documenting things exists along a spectrum. We have lots of tools for documentation. Design docs, commit messages, the commits themselves, JIRA, email, chat. Which one is appropriate depends on the given situation.

the problem is it takes me 2 seconds to run git log to see if a bug has been fixed, vs going to a web browser, waiting for JIRA to load, waiting for a search to finish, curse at search for being useless, eventually find the ticket, and then see if it's complete.

I think you might be missing another dimension, in that it depends on the size and type of bug. "See a problem fix a problem" is a common mantra in physical work type environments I've been in. You don't wait for a manager to tell you to pick up a debris that's fallen in a forklift path. You clean it up. This doesn't quite translate as well to software, you certainly don't just want to make production code changes without some kind of review, but there are things like cleaning up some annoyance around a dev VM image that doesn't require ticketing. A smart dev will likely tell people they fixed it (especially so teammates can update their VM), and a smart manager might document that fix with a ticket for their metrics, but my experience, is that organizations that laud autonomy in these kinds of improvements tend to have significantly greater actual velocity than ones that don't. I've lived through an org that reprimanded any change that wasn't documented (or really dictated) and it creates an atmosphere of apathy and distrust. The same org over time finally had enough personalities who lauded initiative that it was transformative, and the apathy evaporated.

This is not how it happens in my experience. The other developer, who sees their teammate's daily updates and code reviews, would just say "oh this was fixed yesterday". The manager trying to assign work is a tedious redundancy here; the engineers do a better job of owning the problems if the manager goes away.