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.
