6 ms·

> Fixing a bug or delivering a feature where you haven't documented the process, (how the criteria were decided, when it was tested and deployed) is as good a

by mdoms 6y ago

> Fixing a bug or delivering a feature where you haven't documented the process, (how the criteria were decided, when it was tested and deployed) is as good a running a web site nobody visits. Sorry but what? You might need to expand on this. As far as I'm concerned, when a bug is fixed then the value of that fix is realised by the users. I don't see how this is not valuable just because you manager didn't get to eyeball the ticket.

marcc 6y ago
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.
- d23 6y ago
  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.
  - marcc 6y ago
    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.
    - stefanmichael 6y ago
      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."
- xxpor 6y ago
  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.
  - Kwpolska 6y ago
    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.
    - pm90 6y ago
      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.
      - tharkun__ 6y ago
        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).
johannes1234321 6y ago
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.
- milesvp 6y ago
  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.
  - johannes1234321 6y ago
    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.
  - coredog64 6y ago
aqme28 6y ago
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."
- curryst 6y ago
  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.
- prepend 6y ago
  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.
  - pm90 6y ago
    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)
    - prepend 6y ago
      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.
antaviana 6y ago
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/ https://xkcd.com/1172/
asciident 6y ago
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.
- ajkjk 6y ago
  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.
  - maccard 6y ago
    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.
    - ajkjk 6y ago
      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.

by mdoms 6y ago

marcc 6y ago

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.

d23 6y ago
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.
- marcc 6y ago
  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.
  - stefanmichael 6y ago
    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."
xxpor 6y ago
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.
- Kwpolska 6y ago
  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.
  - pm90 6y ago
    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.
    - tharkun__ 6y ago
      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).

johannes1234321 6y ago

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.

milesvp 6y ago
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.
- johannes1234321 6y ago
  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.
- coredog64 6y ago

aqme28 6y ago

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

curryst 6y ago
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.
prepend 6y ago
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.
- pm90 6y ago
  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)
  - prepend 6y ago
    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.

antaviana 6y ago

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/ https://xkcd.com/1172/

asciident 6y ago

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.

ajkjk 6y ago
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.
- maccard 6y ago
  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.
  - ajkjk 6y ago
    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.