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