[notyourwork]

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.

[nix0n]

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.

[eropple]

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

[docmechanic]

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.

[eropple]

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

[mr-ron]

Those ad-hoc doc updates are the exception vs the norm.

It is also common to have controls in github, where its required for a jira ticket to be attached to a PR.

In that situation. Its literally impossible to merge into the codebase without a ticket.

Again it comes down to 'who can create the ticket' and 'what is the required scope of the ticket'

[eropple]

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

[est31]

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.

[mr-ron]

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.

[est31]

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

[eropple]

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.

[sanderjd]

Why are PRs more likely to fall through the cracks than tickets? I think the opposite is the case...

[icedchai]

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.

[ozim]

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.

[icedchai]

Some process is necessary, for sure. However, if they only had one paying customer, sounds like they had bigger problems than no controls.

[sanderjd]

> It is also common to have controls in github, where its required for a jira ticket to be attached to a PR.

Maybe that's common, but it does not strike me as a good practice.

[mikevin]

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.

[sanderjd]

> And, it's normal for a PR to need a ticket.

Why?

[icedchai]

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.

[sanderjd]

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.

[rleigh]

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.

[sanderjd]

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

[icedchai]

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.

[sanderjd]

Sounds like a good thing to fix.

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.

[mr-ron]

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.

[knightofmars]

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

[mr-ron]

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.

[sanderjd]

Could you point me to where in the regulations it says you must have a duplicate paper trail? A PR is already a paper trail...

[rleigh]

A PR is most emphatically *not* a paper trail.

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.

[sanderjd]

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.

[eropple]

> Done right, its not a limitation at all

Context switches are limiters, IME. Smash somebody's stack and you've made them useless for half an hour.

[mr-ron]

This is why tickets can be used to protect the engineering team. You dont want people ad-hoc adding scope, or interrupting work for engineers.

You want engineers to have focus time, on a clear actionable item, that is set up for success, and will add value.

Allowing engineers to work on whatever they want, or change scope on what they want, without saying 'why', can end up creating a lot of wasted work.

[eropple]

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.

[mr-ron]

Yes I agree and thats why Scrum / Agile gets a bad rap around here.

[ozim]

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.