[mr-ron]

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.

[lostdog]

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

[mr-ron]

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?

[lostdog]

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.

[mr-ron]

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.

[sanderjd]

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.

[plorkyeran]

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

The PR? Whatever you'd write in the ticket you can just write there instead of splitting information between two places.

[carlisle_]

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?

[mr-ron]

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.

[carlisle_]

We’re still talking about updating documentation right?

[azemetre]

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.

[mr-ron]

I think we started there but have extended into a different discussion as to 'why is jira important to engineering teams'.

[carlisle_]

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.

[treis]

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.

[mikevin]

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.

[carlisle_]

For updating internal documentation? I think we should be careful to ensure we’re actually adding value when we add friction, and not just hoping.

[mr-ron]

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?

[carlisle_]

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.

[mr-ron]

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.

[sanderjd]

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.

[treis]

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?

[synu]

Let’s first open a ticket to have a discussion about the ticket opening process, and from there we can get a ticket open to open your proposed ticket.

[ipaddr]

Can you fill out this form in triplet?

[carlisle_]

Can you explain why it’s necessary I need to write a ticket to update documentation?

[disgruntledphd2]

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

[treis]

I did. To give your team visibility into what you're doing and why.

[sanderjd]

Oof, if this really needs to be explained, boy I just really don't know...