I mean, thats pretty normal for any stage tech organization.
The question is, who gets the right to create a jira ticket? Maybe you can do it, or just one other person. Thats not a big limitation at all to moving quick.
Edit because this is causing a stir:
Engineers within teams should have the right to create tickets themselves. Tickets should be minimal depending on the task. Creating a ticket that says 'update documentation' may take 10 seconds. Updating documentation may require a pull request. Controls (SOC compliance) may require that work is tracked to tickets.
The core questions I have is, who can create the tickets, and how detailed do they need to be?
I disagree with it moving quickly, all it does is encourage me to not update documentation and not actively improve the code in other ways due to inane bureaucracy. And surprised surprise, no on else on the team wants to document anything either; people get burnt out because they have no autonomy and just leave.
All is good tho! We followed the process and that's the only thing that matters.
I wonder what the corporate equivalent to "I was just following orders" is?
If an engineer can create a ticket and work on it, thats not reducing autonomy. Thats adding accountability.
If documentation requires a pull request / merge to update, often you have set controls that require a jira ticket. Its super common to not allow engineers to make solo commits without a pull request.
If an engineer sees the creation of a jira ticket as a limitation, or if they are not empowered to create their own tickets, then Id agree its a problem.
That ticket is just adding friction to getting things done. Why can't you track the pull request itself?
This one instance of friction might but seem like a big deal at first, but the attitude is what causes slow development and burnout. First there's this tiny process, and then why not add a few more bita of process on top, until finally your merge process takes longer than writing the updated documentation, and so people stop doing it.
Instead of asking "why can't you just do this process," you should be asking "why is this process necessary at all?"
Imagine the inverse where you have a team of engineers working on their own projects. And you dont know who is working on what, or why. Because there is no pull request yet.
Who requested this change? What is the scope? Where is the upfront documentation?
Now imagine the PR is ready to be merged. Since the engineer doesnt like documentation (as you are suggesting) then theres little context into what this is doing, who it will affect, and what types of changes can be expected.
Now imagine those PRs create a bug and causes an outage. Where do you look to determine the context into why this decision was made?
Now imagine a dozen of these teams working on the same repo. How do you coordinate who is working on what and what types of releases need to be schedueled?
I don't know what to tell you. You're describing a highly dysfunctional organization with no autonomy and extreme micromanagement. The right answer to all your questions is "leave, and try to work for a good manager in the future."
It is useful to do project planning and task tracking at a high level. But it's counterproductive to open a ticket every time you want to take a breath.
I lead a highly productive team in a challenging technical area. I know roughly what team members are working on in a given week, and that's enough to do coordination. Individual engineers write good pull request messages, and supplement it with design or usage documentation when necessary, and that's more than enough to understand what's going on.
My comment above is describing a place that is all autonomy and no micromanagement to the extreme. Its a place I worked before I understood the value of upfront documentation.
The situation Ill describe as a good place to work is, you have tickets that are created (by engineers / product / business whoever) that are evaluated ahead of time, and the team determines if it will add value to the business /end user, scoped appropriately, and set up for success with timeline and work.
As many decisions as possible should be made by the team doing the work, and they should be empowered to change their process as necessary.
The micromanagement is implicit in your use of the word "you". "How do you know ... ?". Who is that "you"? If it's the person's manager, the answer is "because we talked about it in our 1:1 or on chat". If it's anyone else, the answer is either "don't worry about it" or "coordinate with the manager". It's good to have a plan for the week / month / whatever timescale, to help teams coordinate with each other, but you really don't need real time visibility into what a team is up to if you aren't on the team.
Is creating the ticket really adding value to the engineering process? In your example you already have the engineer making a PR (presumably peer reviewed) and a commit, what’s the ticket really needed for?
It can add value if done right. Just as you typically want to make a design doc / rfc before working on a project, you often want to describe what you are doing before you do it.
This can protect the engineer / team against scope creep, as well as determine the context of why work was done when you may need to understand more context (in the case of a bug for example).
Also it increases accountability and transparency. It is common that teams want to know what other engineers are working on and why.
I'm explicitly referring to internal docs for the engineers that no one outside the team sees or cares (unless they want an example of docs). They're mostly markdown files or adding annotations to various code. I still think it's inane and seeing all the justification for "believe in the process" it's no wonder how little truly gets done in the name of agile/scrum/control.
I think you made that leap, but I was responding to the specific example. I don’t think anybody is contesting the use of tickets in engineering, but I’ll certainly oppose the idea that Jira is important.
It's not a lot of value but it's also not a lot of effort. At minimum it gives a little bit of visibility into what you're doing and why to the rest of the team. That's probably worth the 2 minutes it takes to create a ticket.
I don't think it is. We're all professionals, if I'm doing something they need to know about then I'll inform them.
A ticket that takes 2 minutes to create is just distracting from tickets that provide real value to my colleagues. We're here to work together and improve something, not to babysit each other's schedules.
"Visibility into what I'm doing" as a reason to create a ticket is relevant for micromanagement, not for a team of professionals that trust each other's commitment to the job.
What is the scope of this documentation change? Is this a quick edit, or is this a whole new tutorial for new engineers getting their stack up? How long is this going to take?
Do you want an engineer every standup saying 'im working on documentation' without any accountability?
You really want to add friction to completing those tasks? How long does it really take to complete any one of those things, and how is a ticket going to change the fact it probably needs to get done anyway? Why am I going to write a ticket for docs I can write in an hour and be done with? Why would you want the docs to stay out of date until a ticket is created, rather than just fixing them?
Frankly I think you missed the point of the article. If you don’t trust your engineers to prioritize their own time when it comes to writing documents, you don’t trust them to do anything. You’re exactly a part of the problem that Will is talking about.
I dont really think you are grasping what I am saying. I want engineers to make tickets, and prioritize their time themselves. Creating a ticket to update docs is fine because it allows the engineer to set the scope, and define the audience.
That said, I dont want an engineer spending days on a task that will not bring value, nor do I want work done that will fall through the cracks, or have duplicate work done.
Asking an engineer to create a ticket to create documentation is not the hurdle you think it is.
I'm a successful engineer. I hate JIRA. I like keeping docs up to date, but if you're gonna make me deal with JIRA's BS just so I can do a quick doc PR, guess what, no updated docs for you.
They want full visibility into what everyone is working on all the time. Some managers, especially non-line managers, really like this idea. I can understand why, it sounds really good! Transparency can't be bad, right? In practice, it works a lot better to create fairly small teams, let them run independently and opaquely to the outside, and then coordinate between them periodically (bi-weekly, monthly, quarterly, whatever is found to work best).
I think one key thing those folks miss is that willpower is a limited resource. For me personally, dealing with bureaucracy drains it much quicker than my actual work product, writing and designing code. Making me track everything is thus a strong net negative on my output.
I'm senior enough to know what I'm doing, so don't make me waste my (and my company's, they're paying me after all!) time.
The original scope that started this thread was "a quick edit". The claim is (or seems to be) that it is not too much friction to require a ticket for everything, which would necessarily include these small edits. That's stupid and will discourage small edits, which is bad, is what people are saying here.
> Do you want an engineer every standup saying 'im working on documentation' without any accountability?
Yes? It isn't any of my business, unless I'm that person's manager, in which case I'll certainly use my 1:1 with that engineer to understand what the documentation changes they're making are all about, and if it seems like a poor use of time then I'll give them a nudge. But if I'm anyone else in this situation, I'll certainly mind my own business.
I'm sure talking about having to update internal documentation has value. Can you perhaps elaborate on why 2 minutes to write a ticket is such a burden?
I think he did, and the answer is SOC compliance. I learned something about this compliance from his comment, and it'll encourage me to write these tickets next time (my current org is going through this process right now).
Which comment? The one in this thread doesn't seem to explain this. Does SOC require a Jira ticket for every change or does it require an audit trail? If the former, that's stupid, I'm happy to comply with stupid regulations, but I'm not going to gaslight myself into thinking they aren't stupid. If it's the latter, then that makes perfect sense as a regulation, but the commit history of the repo or whatever other versioning system you use for your documentation system can meet that requirement.
Why does my team need to know that I spent two minutes fixing typos in engineering documentation? Also, if they do want to know this, they can subscribe to the changes being made to the documentation repository / system and then they'll see what I did.
Is this really for visibility within my team? Or is it for some kind of external visibility?
>Is this really for visibility within my team? Or is it for some kind of external visibility?
Both.
>Why does my team need to know that I spent two minutes fixing typos in engineering documentation?
Nobody said typos.
>Also, if they do want to know this, they can subscribe to the changes being made to the documentation repository / system and then they'll see what I did.
How is that more efficient than you taking 30 seconds to write a ticket and 15 seconds to talk about it on stand up?
If it was important enough to go update the docs why isn't it worth the 1 minute to tell your teammates about it?
Nobody outside the team needs a single iota of visibility into my efforts to keep our internal documentation tidy. Anyone who is keeping tabs on this is wasting their time and needs to find something useful to do.
> Nobody said typos.
The claim in this thread is that a ticket is necessary for all changes, and fixing typos is a change.
> How is that more efficient than you taking 30 seconds to write a ticket and 15 seconds to talk about it on stand up?
I'm so confused. The "that" here is making the change itself vs. making the change itself and doing two other things. The way it's more efficient is that you do just the one thing, instead of that one thing and also two other things. Maybe I don't understand your question...
>Nobody outside the team needs a single iota of visibility into my efforts to keep our internal documentation tidy. Anyone who is keeping tabs on this is wasting their time and needs to find something useful to do.
This is naive. Someone above your team is superficially watching how much work your team does. If you don't document it then it doesn't get counted. You want it to get counted if you care about promotions and raises.
>The claim in this thread is that a ticket is necessary for all changes, and fixing typos is a change.
Not in this thread. The original complaint is opening a ticket for updating internal documentation.
>The "that" here is making the change itself vs. making the change itself and doing two other things.
No, the "that" is watching a repo instead of you taking a tiny amount of to tell the team you wrote some documentation.
> This is naive. Someone above your team is superficially watching how much work your team does.
It is not naive. Top down micromanagement is certainly common but it isn't inevitable. I have worked in multiple businesses with healthier management cultures. I'm sorry if you haven't.
> The original complaint is opening a ticket for updating internal documentation.
Yes, the rebuttal to which was "that's stupid don't do that" to which the claim was "it's normal to require tickets for every change", which is what I said the claim is. I wouldn't be pushing back on a claim like "nearly every change requires a ticket, but not minor edits to documentation like fixing typos". But that's not what people are advocating here.
> No, the "that" is watching a repo instead of you taking a tiny amount of to tell the team you wrote some documentation.
What thing are you saying is "telling the team"? Filing the ticket? So the team is subscribed to the feed of new tickets then? Why not just be subscribed to the feed of new changes to the repo? What do you see as the difference between those two things? Or is "telling the team" the standup status update about it? In that case, can't I tell them about the change I made directly? How does having a ticket help?
>It is not naive. Top down micromanagement is certainly common but it isn't inevitable. I have worked in multiple businesses with healthier management cultures. I'm sorry if you haven't.
Again with the unjustifiable leap to an extreme. Nobody said micromanage.
> So the team is subscribed to the feed of new tickets then
Yes. Scrum teams do a quick rundown of the board on standup. That's your opportunity to tell them what you did and why.
What you are describing is micromanagement. It is not necessary for you to say that's what it is, nobody ever thinks what they are doing or that what they favor is micromanagement, and yet that's what lots of people are doing. And that's what you're describing.
> Scrum teams do a quick rundown of the board on standup.
This is a major anti-pattern! What's funny is that other people I've been debating with in these threads have made the point that stand-ups aren't so bad because it isn't about status reporting, it's just a really quick get together ritual. And yet this is what lots of teams actually do, pull up the sprint backlog and have a planning meeting every single day.
What you're describing is a micromanaged process of very dubious value. I recognize that this is what lots of organizations do, but (to circle back to the article) it is very much the opposite of what companies like Google do, and not because they don't have tons of compliance and auditing requirements; they do.
No, because not everyone reads PRs. And at this point you're complaining about the 30 seconds it takes to open a ticket and copy & paste. You still haven't provided a reason why that tiny effort is not worth the bit of value it provides. And frankly it just sounds kind of ridiculous at this point.
There are plenty of comments that do a much better job explaining why a context switch isn’t just 30 seconds in this example.
Besides if all I’m doing is taking 30 second to copy and paste something what value is that really adding? If nobody says anything the docs stay incorrect. But when I want to fix an error I need to context switch and open a ticket and copy and paste what I already wrote once? I’d rather just do nothing.
Really though, I’d rather just have up to date docs, so let me update them instead of insisting people do things your way. Fix the problem with people not being able to see the PR, don’t make me do the same thing twice.
What is normal about this? Engineers should be empowered with ownership. Adding. friction or barriers to enabling engineers to make what they own better is backwards and counter productive at best. At worst, it discourages proactive willingness to make an improvement.
If it's in a repo, it's normal to need a PR to change it. And, it's normal for a PR to need a ticket.
Alternatives to creating a new ticket could be:
1) Link to the ticket number that was used, for creating whatever you're documenting now. Use the "blame" report.
2) Link it to a catch-all ticket for documentation or code quality. Look in your ticket system for a low ticket number, with recent activity. If this doesn't already exist, and you really do need to make a new ticket, write it as generally as possible to enable this style of reuse.
> If it's in a repo, it's normal to need a PR to change it. And, it's normal for a PR to need a ticket.
In my experience, the former is true but the latter is extremely not.
Tickets are for tracking concerns for stakeholders. A documentation fix, to use the example at hand, is an ad-hoc improvement for customers/consumers and should have as little in the way of it as possible.
It is standard practice for technical writing teams to link a ticket to all pull requests. Writers, like developers, typically work on multiple pull requests in the same sprint.
If you're not familiar with Docs As Code, I highly recommend giving this a look for some of the current trends and ideas circulating among the technical writing community: https://www.writethedocs.org/guide/docs-as-code/
An example: would a developer publish code without knowing what ticket relates to that code? Nope. Same with current crop of technical writers.
> An example: would a developer publish code without knowing what ticket relates to that code?
Yes? I don't track a pretty significant amount of my work via tickets because I'm working on it largely solo and I have a direct line to all stakeholders to update them.
And I am not a technical writer, but I do technical writing, and I find breaking flow to juggle tickets a great way to get me to not do that documentation work because the opportunity cost of the context switch is high.
> Those ad-hoc doc updates are the exception vs the norm.
Where you work, maybe. Not where I do, or have. If I'm in something and see that I can make it better without losing my stack, I'll do it. I encourage my coworkers and, when managing, my reports (when they have proven that they won't rabbit-hole) to do the same.
What is often pejoratively called "boy-scouting" in a codebase is the only practical way by which many organizations will maintain that codebase beyond feature requests.
They are exceptional the harder it is to make them, and the result is documentation full of minor grammar mistakes or unclear things.
As an example for where it works great, I have made a small documentation fix PR to the Rust standard library 2 days ago and I didn't have to create a github issue for it or anything (but I had to notify a maintainer to review it because the PR fell through the cracks it seems). That maintainer told me they have reviewed 5 other similar pull requests that day. Over time, you get a really nice code base that way.
I think you just nailed it. With the PR that fell through the cracks.
The danger of having a ticketless fix is, you end up with PRs that are not on anyone's plate to fix.
The nice thing about tickets is that it creates a clear line of succession for adding value. If done properly, you will not have anything fall through the cracks. The cost for this is, you need to create tickets.
Reduce the friction to as close to 0 to create a ticket, and you can net all the benefits of tickets without a lot of cost.
The rustc repo has a system to assign PRs to reviewers automatically upon filing. On github, PRs and issues are very similar, and one can assign people to them.
There is a bot which checks which components the PR is modifying and based on that it assigns a reviewer to it. It predates github's builtin support for specifying component maintainers, so is a bit different than that.
However, as the Rust project is mostly made up of volunteers, sometimes a PR gets assigned to someone who is less active. This happened in my instance, where the PR got assigned to a reviewer whose last approval that ended up in a merge was in February 2022. The PRs assigned to these maintainers still get reviewed eventually, by other reviewers, or maybe them themselves. The assignment is more of a suggestion than a strict requirement and often maintainers with a desire to review some PR assign themselves. I just wanted to speed up the process so I talked to a maintainer who I knew likes to go through the list of open PRs and approve them if they are trivial. That's what I mean by "fell through the cracks".
Perhaps you've worked in notably functional organizations, but, with respect, your claims throughout this thread read like theorycrafting. I have been a Jira administrator, I have had extremely positive feedback from all parties based on the workflows, the automation opportunities, and the minimization of overhead involved when I did so, and it still required a context switch. And context switches always and without exception suck.
Ive both worked in and led highly functional, and highly non-functional organizations.
You are exactly right, that much of what Im pushing is the vision of what Agile / Scrum is supposed to facilitate, and what the benefits can look like if done correctly.
The best jobs I've had didn't have any of these control issues.
The worst ones required tickets linked to PRs with multiple layers of approvals, on and on. It could take days to get a few dozen lines of code merged. No thanks.
For me worst system that I had to fix and I had to save the company from losing only paying customer didn't have any of controls.
It was just bunch of freelancers doing what they wanted and paid in gold.
Right now as company is growing I consider leaving from time to time because people we now hired start creating bureaucracy that I would never go into.
Well I definitely introduced process into company - but as I see it there must be some absolute baseline tickets/repo/CI/CD for standards and at least weekly meeting.
I also agree that for a lot of software requiring unit testing (a lot of people writing bs tests just to pass review), requiring 2 or 3 people to sign off PR is just something I would not recommend.
That's assuming a lot about the work environment.
If your have a team full of professionals, trusted by stakeholders then you don't need any of that.
If my teammember decides documentation needs updating he should go ahead and update it. Tickets and PRs are for thing that need planning and reviewing. I trust my colleagues to know when that is the case and decide accordingly. If any of us messes up we talk about it and improve.
In reality this means that many, if not most, things still get tickets / PRs because it helps but the fact that it's not simple ceremony makes sure everyone knows their importance and saves time when they aren't needed.
Some orgs have strict change control processes. "Why is this change happening? What is it supposed to do?" At one place, I used to just submit my own ticket,a assign it to myself, then open a PR linked to it. Totally pointless. At some other companies, it's more open. "We trust you! Just get it done." There is more risk, but it's a better environment for some. Possibly not for all.
I understand requiring such documentation and auditing history, but there is no good reason (or at least nobody has presented one here yet) to do it in both a ticket and a PR.
Have you worked in a regulated environment? It can be a regulatory and legal requirement to do this, since it's part of the software development lifecycle processes which are required to be followed.
At its core, this is about ensuring that the software is not changed without a documented requirement to do so in the form of a formal change request. The PR alone does not do that. The PR is the software change. It is not the request to do the change in the first place.
Some projects and company processes can be sufficiently lax to permit developers to open PRs and change things without any additional accountability or oversight. In these cases, you don't need that extra level of work. But many projects do need this, and it can provide value even outside a regulated environment. Many open source projects require a corresponding ticket for every change as well.
You might also need to make sure that the work meets the "definition of done". In a stricter environment, that can mean making sure that every change ties back to the design documentation and the system requirements, as well as having all of the necessary test and documentation coverage to match, and more. That gets tracked on the ticket, not the PR, because the PR is only about the software change, not the higher-level stuff.
Another factor is that the ticket is what has the visibility. Not everyone in the company is necessarily directly involved with the nuts and bolts of the version control system. When it comes to the higher-level aspects of project management, particularly on large projects with multiple teams, you aren't going to be doing that with GitHub, but you do need to coordinate activity and account for where the development effort is going for planning and resourcing purposes, even if the metrics are only used within the team.
None of this means being hidebound by process. For a trivial documentation change or bugfix, there's nothing to prevent keeping this overhead to the bare minimum. It takes 30 seconds to create a new ticket before opening the pull request, with a title and possibly a sentence or two description. That can greatly help the other people in the company see what is being worked on, what's been fixed, what's in the backlog and where effort is being spent. Ultimately, we aren't writing software just for our own amusement, we're doing it for others, and the tickets are part of communicating and coordinating our activities with other people, even if it appears superficially onerous.
Can you give me example regulatory language that would require a Jira ticket in order to change internal documentation? (That is the only thing we are discussing in this thread, despite many attempts to broaden it.)
An internal engineering documentation change is not something that needs visibility in this grand project management effort. Project managers that are tracking such things are doing busywork that is not adding any value.
I recognize that all of this is very common, but it's not actually valuable. I have absolutely zero problem abiding by rules that are not good, but what I see a lot of here is learned helplessness and rationalization. It is not necessary to convince oneself "actually this is all good" in order to merely abide by rules that it is not your responsibility to change. You can merrily follow the rules and then also, if anybody asks you, you can say "these processes are not valuable for the following reasons".
The documentation itself can be regulated, and changing it requires more than a PR code review by another software developer. As an example, the instructions for building and releasing the software could come under the controlled SDLC process.
I see where you're coming from, but you're not correct that this is misguided, nor that this is just busywork for project managers. If you're doing safety-critical stuff in the automotive, aviation or medical industries then process faults mean lives could be put at risk. A drive-by PR to update a document could have serious implications, and that's why change management processes are in place. They are a safety-net above the level of the code review and activity in the VCS, because you have a different set of eyes on what's going on.
I know there is some fallacy or something around asking for evidence (is it "sealioning"?), but are you aware of anything that demonstrates that this kind of change control process successfully reduces risk in life-critical systems? I'm very skeptical that requiring a ticket requesting an internal documentation change in order to improve that documentation is saving any lives. You might say "well it can't hurt", but I don't think that's obviously true; I think it creates a perverse incentive to leave documentation as is rather than improving it, which I think is more likely to be negative sum than it is to be valuable. That is why I think it is misguided; I think it is more likely to result in poorer documentation, for no gain.
Please understand that I really am just talking about this one case; I see no reason to question a requirement like this for changes to code or configuration or interface documentation or specifications or anything else.
An example is when all hours spent need to be traced back to a requirement that has been signed off on by stakeholders. There needs to be a recordkeeping system to support this requirements traceability, so Jira it is.
Is that a regulation? It sounds like either an internal process choice or a contract requirement.
Edit: But point taken. I can see where this would be a (misguided, counterproductive) requirement in a probably-government contract. I would just suggest recognizing that it is a necessary evil when doing that kind of work, but not a good practice.
At a previous org, I discovered most of the product management folks did not have access to github. So if someone (not an engineer) was trying to figure out why Joe changed feature X, they couldn't do it with a PR. They only had access to Jira.
Edit to add: But also it seems like there are two things going on in this thread. On the one hand, the reason for tickets is (supposedly) for a compliance audit log. And surely the auditing system could read from both Jira and GitHub. But this question of what product managers can access is a different one. I think the more likely reason for these rules is for "product managers" who are really acting as project managers and are trying to micromanage through tickets.
What is normal about this that Ive seen is work and tickets is often written into controls that are required for things like SOC compliance. And documentation often requires a pull request.
And again read what I said, that engineers can and could be empowered to make these tickets, which can be minimal at best.
Done right, its not a limitation at all, and instead adds accountability.
"...things like SOC compliance." This is an important point. If you work in a regulated industry or work with software used in a regulated industry you need a "paper trail". Having to document and follow a process is often frustrating to people who work or have worked in industries that don't require it. That said, a poorly implemented process in a regulated industry is even worse. As you're overloading teams with busy work and likely still failing to meet the requirements of the regulations you're following. Regulated software is not a place to "move fast and break things" that's what prototypes that never see the light of production are for. Build it without regulation to figure out how to do it and then build it again following the documentation process. It may sound odd but having a second chance to correct errors of assumption from the first time around is quite valuable, buying information when done right is a great tool.
SOC compliance is indeed a beast. I have my own theories on how valuable this benchmarks REALLY is, but if teams are in a financial org, it is super common to have controls that have the potential to really hamstring teams.
Which is doubly important to really understand the vision of agile / scrum, and not just follow the ceremonies by the book.
It's recording a software change, who made it, and when.
That isn't even close to the bare minimum for some of the regulatory requirements.
You're coming to this with the perspective of a typical software developer. I can sympathise greatly. But the regulations aren't about software development. They are about risk management and product quality, and putting in place processes to ensure projects deliver solutions which are safe and robust, due to having the appropriate controls in place. This isn't just about the software implementation. It goes all the way up to the specifications, designs and requirements and it requires testing and validation work at every level.
I have only in the last few years been working in such an environment. It was eye-opening. Compared with the free-for-all which is most software development, this is actually about engineering robust systems, in a very systematic and rigorous way. That does include some overhead in the processes surrounding the development work, but it's there for a very good reason.
I'm very familiar with this kind of compliance environment. I spent quite some time working on a committee focused on similar issues (privacy requirements in my case) and I certainly understand the value of auditability and the existence of requirements like this.
We are talking in this thread about a very specific subset of this: Does it make sense to require a Jira ticket for a change to internal system documentation.
I don't have experience with SOC in particular, but I would be very surprised if the regulations specified "you need a Jira ticket for every change to every kind of documentation". That would certainly be a very big lobbying win for Jira! But I suspect it is more like "you need to be able to audit and trace the purpose of all documentation changes". The trick in designing the processes used to comply with such requirements is figuring out how to balance compliance with process friction.
If you are in charge of this sort of thing and your instinct is to never challenge the usefulness of busywork and ignore feedback on its impact, like the kind of feedback in this thread that is being ignored, then you are not doing your job well.
Tickets can, theoretically, be used to protect a development team. I agree with you there. But they usually aren't, and most folks are living in the land of what-is, not what-can-be.
Even not SOC compliance just liability of a company.
If stuff fails and company gets sued - they will have to prove that they "follow industry standards" because if they don't follow industry standards then all kinds of bad stuff can follow.
IF you get ransom-ware and have an insurance - see the exclusions - you have to have EDR software on each server otherwise insurance won't pay.
Not following industry standards in terms of code - the same no insurance company will pay if they catch you on just doing stuff.
So running a business all kind of BS and it is not optional and just slinging out code is not enough.
I find this whole back-and-forth fascinating, because it mirrors my experiences in the workplace. There are some people who really like process around everything an engineer does, and some people who really don't like it. They're almost two distinct personality types, and it's virtually impossible to get them to agree because it's like asking someone to change their personality.
I happen to be one of the types who dislikes heavy process-oriented project management, and reading mr-ron's responses is admittedly making my blood boil. But I bet he reads some of the responses to his remarks and probably has similar reactions.
Some people thrive with heavy process, and some people wither. Some people thrive with light-weight process, and some people wither. I don't know how to structure an organization to support both types of people in it, but it's not an easy problem to solve. That's why there are so many project management methodologies, with new ones popping up every few years and then inevitably disappearing in favor of something new and better.
I think the solution is to do everything you can to keep the heavy process people away from anything important for as long as possible, before you get too big and they manage to embed themselves anyway, where they will commence to expand the bureaucracy to meet the needs of the expanding bureaucracy.
What a great comment!
The whole, every change needs a ticket debate is interesting but without context. Some orgs require it and you can just create a ticket and move on. Fundamentally I don't view these tickets as useful, if asked "tell me the latest state of X", or "why was Y done", the tickets rarely help (and if they do, the proper places of commit history or the code itself skimp on these)
The tickets can often go on to be "for the devs we like and trust, they can cut tickets", but for the others we require they're prioritized. This creates a lot of chafing, that quick bug fix, is it worth context switching now to create a ticket, again later to explain it to the non-technical prioritizer of tickets, worth the argument of why a "business goal" should be deferred to prioritize this ticket, the tracking overhead to finally say you are selecting ticket X, and that final context switch to actually work on it? All that compared to just fixing it, switching branch and cutting a pull request a minute later
I found I liked tickets to identify product work, so maybe 5% of my commits actually reference tickets, the rest are supporting changes that enabled that 5% to be done cleanly or are just things that should be fixed or cleaned.
Coming back to it, tickets have their uses: documentation, discussion, prioritizing. But tickets can quickly turn into "this is how we keep our engineers from cleaning up the code, etc", "this is how we do programming by remote and control exactly what is worked on." Worst, it is the self inflicted burning the midnight oil, "hey, you said this was going to take a week, estimation is a skill of a senior engineer - will this be done as promised, or is your ability to estimate not there yet? Wink, the sprint is over on Monday.."
FWIW, I agree with timmytokyo's assessment of 'heavy process'. I actually worked in a place where PR's need to be tied to tickets and updating documentation is the perfect example of where it sucks. Imagine you're trying to debug a bug, looking through the stack trace and trying to reverse engineer what the heck is going on. You find a block comment explaining what should be happening, but it's not been updated in years and not technically relevant to the final bug fix.
You've got two choices, either you sneak the comment block change into your PR, despite it being irrelevant and make the documentation update blocked by the bugfix/feature. Or you need to open Jira, make a ticket etc etc. I know you say it's 30 seconds, but it's not. It's at least two minutes, but it's not even the time that makes it annoying. It's the fact that you're doing something that you(the people timmytokyo describes) think is entirely pointless.
I ended up writing a janky git hook that would check if the branch name I was pushing had a jira-id in it, and if it didn't it would use the Jira API to make the ticket, grab the id and push the branch again with the id in the branch name. The fact that the entire thing can be automated, makes the entire thing pointless in my mind.
The thread gives me very strong vim vs emacs vibes :).
So the main difference is that CI tests provide useful information, whereas automatically creating a ticket from a commit provides 0 useful information, it just duplicates data.
The other difference is that CI tests do actually run automatically. If you had to go into github and press "run tests" every time you make a PR, that is a waste of time.
But sure, if there was a server side hook that automatically created Jira tickets for PR's without tickets, then the entire thing is less annoying. I still think that's a net negative since it creates noise in Jira, but it's not as bad as forcing engineers to do automatable work.
I agree that my wording was not perfect, hopefully the extra explanation makes my point clearer.
It feels heavy to me, because you're asking for a process gate to be put in front of something that is so trivial. It feels utterly unnecessary and demotivating. If I see a minor problem in the documentation and decide to correct it, now I have to go through an extra step of creating a JIRA ticket describing the minor problem I'm trying to solve, doing the correction, updating the JIRA ticket status, and possibly monitoring the ticket for future issues. It's. all. so. bureaucratic. And sadly it will probably lead me to thinking the fix is not worth my time.
Instead of trying to convince everyone that they should feel the way you do, maybe try to understand why others feel the way they do.
I think the answer to all of this is 'it depends'.
Is there already a ticket and are you working to update the app? Then update the documentation. No ticket necessary.
Are you redoing the whole set of docs to make the steps for new engineers to create their stack? Then please lets have a ticket to define the scope and audience.
Trust me that I do understand that there are many orgs that have arbitrary hurdles in place, like who can create / prioritize a ticket. My experience is, if engineers are empowered / encouraged to create and prioritize their own tickets, then its not a hurdle at all.
> if engineers are empowered / encouraged to create and prioritize their own tickets, then its not a hurdle at all
Many people - now including me - are plainly telling you that it is a hurdle for them. No amount of reframing this is going to alter someone else's experience.
You seem to keep trying to change the subject to "should there be tickets in general?", which nobody is saying there shouldn't. The topic is "should there be a ticket required for every change, which requires tickets for updating typos in internal documentation, because that requires a change and you propose that a ticket be required for every change. That is stupid, to require a ticket for that. These other examples are not stupid to use tickets to track them. But they aren't the subject of the thread.
Nah, I can just make a task and make whatever UI tweaks I want. I mean, someone will probably complain about it eventually if I make some crazy change to the UI, but there's no process stopping me from doing so. Other than the handful of clicks it takes to make myself a task for the work.
It’s not really 30 seconds though is it, if everyone is making all these tickets to do trivial things, they are getting update emails on them whenever their micromanager gets around to acknowledging them. It’s generating all the work for people to look at all these trivial tickets. You already have a source of truth on what changed - the PR. Forcing a fellow human to make a ticket that is just a link to a PR is Kafkaesque regardless of whether you “empower” your engineer to open and then immediately close her pointless tickets on her own or not.
In my experience, there's a threshold where a ticket just generates net noise on the process, which is why I don't like tickets even for things like updating documentation in code.
If you multiple that "just 30 seconds" by several trivial things you encounter each day that aren't part of your assigned lot, it adds up. Those new tickets show up in your list of tickets, so now you have several line items that have to be walked through during sprint planning or daily standup so everyone knows what's going on.
It's true that perhaps other devs want to know about that ticket to update some documentation, but it may be such a minor change that it seems silly to have to do a song and dance about it during standup so everyone has full context. And often, not everyone needs to know about every little change that is made anyway.
Then, when you look at the work to be done, the large list of trivial tasks makes it hard to see the 1 or 2 really important tasks that you're really working on.
I think the dividing line here between pro-ticket vs. not is based on how much you trust your fellow devs to the right thing and how much trust you have overall in your team as an organization. If you have little trust that people will do the right thing, you'll probably want to create a ticket for everything to make sure it doesn't go astray. Unfortunately, for those with more experience and better judgment about what is the right thing to do, they'll just feel constrained by the whole thing as it removes agency.
... they are getting update emails on them whenever their micromanager gets around to acknowledging them ...
You just nailed the problem here. If the process is set up that an engineer cannot create / prioritize / close trivial tickets themselves, that is indeed true friction.
Those problems never come in isolation. If the developers need to do useless tasks for being through, the odds are really large that they also need to answer to them for management.
A ticket supposedly represents some worthwhile task that's worth specifying. If it takes just 30 seconds to create it can't possibly concern a task that's worth the cost of involving ceremony/process.
> If while reading a document, you find a mistake, instead of changing it, the normal reflex is to create a Jira ticket?
I would say the first reaction is to create the PR to make the fix. Then, while CI is running, I create the JIRA ticket and update the PR description to point. Best of both worlds!
It depends on the documentation. Is it within a repo? Does it require a pull request? Is it a quick edit, or is this a multi hour effort that is redoing the scope?
Cute Agilist gaslighting about not needing a ticket because that’s “asking for permission” and it’s supposed to be implicitly bundled into feature work.
”Tickets should be minimal depending on the task. Creating a ticket that says 'update documentation' may take 10 seconds”
This type of placeholder-documentation is literally the WORST type of tracking you can have. And a sign that everybody in your company forgot the reason why this type of traceability was implemented in the first place.
If I review a PR that links to a Jira ticket that says absolutely nothing except “update documentation”. What’s the whole point?!
What’s worse is when people see a link to a Jira as an excuse to write bad commit messages.
I would much rather read a commit message detailing out the background and rationale of the change, rather than a nonsense commit message linking to another nonsense kpi-chasing Jira ticket.
PRs are code reviewed anyway so it’s not like you have a bonanza of unknown changes being pushed left and right. Code reviews not only catches coding bugs but also accountability within the team, eg “why are you refactoring something that works, when our backlog has 100 other more important things to do.”
Is it? I've never needed a ticket to make off the cuff improvements. A PR and a review from other engs to make sure they agree, certainly, but a ticket for that seems like a certain degree of dev micromanagement/big brother/power trip for highly paid and skilled professionals.
At my previous gig we reduced the friction for doc contributions to just a PR but with no review requirement; if the contributor felt the need for feedback or review they would seek it, otherwise just merge the changes.
That's a stupid compliance requirement, unless documentation changes aren't themselves versioned (which they should be). You don't need to track the exact same thing in two separate places.
The question is, who gets the right to create a jira ticket? Maybe you can do it, or just one other person. Thats not a big limitation at all to moving quick.
Edit because this is causing a stir:
Engineers within teams should have the right to create tickets themselves. Tickets should be minimal depending on the task. Creating a ticket that says 'update documentation' may take 10 seconds. Updating documentation may require a pull request. Controls (SOC compliance) may require that work is tracked to tickets.
The core questions I have is, who can create the tickets, and how detailed do they need to be?