I don't think the comment was implying that a manager has to eyeball the ticket to make it worthwhile. The comment said there's value in documenting the process, and I agree with that.

We use a ticketing system to track work. It's not Jira. But we do have a requirement that all work is tracked in that system. It's not so that a Product Manager or Engineering Manager can chime in and micromanage; it's so that we have a record of the fix that's easy to find, track the conversation around it, and be able to reference it 6 months or later. Documenting how it was fixed and tested and verified is very useful. Having a place for a manager to eyeball tickets before they are working is not the value of the system.

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.

Who is claiming that if a bug fix fixed and not documented meticulously in JIRA it is as useless as if it was never fixed at all?

That's not my intent as the parent here, or the point I'm seeing or picking up from this thread. There's value in documenting in a system (Jira is one choice), but I know that I'm certainly able to see value in building a system and a process and then trusting that developers use them when appropriate and know when they are not adding value.

The original poster in the thread we're in:

"Fixing a bug or delivering a feature where you haven't documented the process ... is as good a running a web site nobody visits."

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.

Wow.

For a manager, this could easily have been written as:

It makes me 2 seconds to look in our issue tracking system to see if a bug has been fixed, vs opening a terminal, find the project, curse at grep for being useless,...

Of course omitting steps in your favorite solution makes it look easier.

And how is testing/validation tracked in how you use git?

Most of us don't work in a vacuum without managers, testers, customers.

And for the record, I as a developer also hate Jira, but we have to look at a reasonable solution.

Let’s face it, most git logs have one-liner commit messages that may or may not describe the issue at a very high level. Even if you have long commit messages, they still are less likely to contain extended discussions about the issue (which can be useful many months later), and cannot be edited. In many places, commits are expected to have the Jira/bugtracker ticket number in the commit message, so that if I find the bugfix via a git log (or git blame), I can quickly find the ticket with the extended discussion and other details that might be important.

Except when the linked ticket is just a title with no content.

However, I would argue that even some of that metadata is better than no metadata. At least the ticket can provide some clues for anyone who is investigating a change.

I feel like GitHub issues are good enough for this purpose; unfortunately GitHub charges a per user license fee meaning that most non engineers don’t get access by default reducing its usefulness.

Which means that the creator of the ticket does not understand the value of the ticket and is just forced to do it by process and so does the minimum required for Jira and his other tools to let him work.

Github issues are basically what a Jira ticket is. Just with less of the other stuff around it feature wise that Jira has. How your company uses Jira is not what makes Jira good or bad. Jira can either be used in an appropriate way or it can be customized into a big rigid process machine that we'd all hate. Been there done both. I like being in the Scrum Master/team lead position to try and influence things into a "less process" world. Ultimately I'm probably still 'hated' by the Devs because there's 'too much process and Jira' and the higher ups don't like it either because they don't 'have enough control' (actually illusion thereof).

Elaborating on your point.

When has JIRA actually been effective as the documentation for a bugfix? JIRA in its most effective will just tell you whether we agreed to do this work and the state the work is in. It is not "documentation."

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

It depends on your organisation size and structure, but probably you want to run the bug fix through some triage first (meh management overhead, but needed if you have many bugs to make sure the "important" ones are fixed), then code review (well, that doesn't happen in jira, but probably should be (automatically) reflected there to have one place to look later) and after fixing probably should be routed to the documentation team so docs are being updated and to support team so they can talk to customers accordingly.

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.

Yes, there is value in that and it's a thin line. However if it affects external behavior it is some form of product decision, which eventually needs to be signed off and it has to be documented in some way.

Of course a typo fix in a comment (to find something even more trivial than your VM example) doesn't need a process. But that's also not what I'd call a bug.

Typically how I've seen this work in high-functioning environments is that devs aren't scheduled at 100% according to JIRA. They have time set aside in their schedule for work of this nature. They'll fix the bug, create a JIRA for the commit/PR, and get on with things. The coworkers on PR reviewers and get their notification that way or in standup. If it's more than 30 or 60 minutes they might log some time against it.

On a team I was on, there was a rule that we simply wouldn’t bother documenting 1 point JIRA tickets as then the documentation itself would likely take more time than just making the change.

That reasoning is weird to me. I could live with "there is no impact for users on this" but if it has impact for users (there of course is a difference between developing a library where a lot of things have impact from a GUI application where most things are invisible to the user) it should be documented, even if documentation takes three times the time. Good documentation is part of a quality product.

It's not valuable because then later a manager will still assign the work to another developer, who will spend almost the same amount of time trying to reproduce the bug and finding it fixed. This leads to several back-and-forth slack group slacks to figure out that it was already fixed, and decreases morale. It wastes as much time as if it weren't done at all.

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.

I work on a team of 70 developers (directly) and another 50 or so work on a shared code base between our project and others, and I make daily modifications to that shared code. all those developers are spread from PST to CET+1. Bugs that get fixed are sometimes done by domain knowledge holders on he base team, and those fixes are large fixes that get done on a different release schedule to mine. Its an utter waste of time for me to bug some guy in Seattle about something that he fixed months ago in a release that I haven't received yet when I can see the fix version and change in jira, and either wait or take the fix from the upcoming release myself.

It really depends on the situation. If you have a small team that owns their own codebase, then people will generally know what's going on. In a large codebase with multiple branches it's going to be messier. If everyone's sharing a bug tracker it should be easy enough to claim bugs you're working on.

For the short term, yes. For the long term, if you do not document the reasons of the changes, eventually you will not remember what the reason was for that change.

In software products with enough large bases, some changes decisions affect other users, who eventually might request the change in the opposite direction.

You do not want to lose the rationale behind the original change/fix.

Keep in mind that what is a bug for some users is a feature for others: https://xkcd.com/1172/