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 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.
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.
Do you want an engineer every standup saying 'im working on documentation' without any accountability?
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.
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.
Where was the value created again?
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.
> 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.
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.
I'm a developer and 30s is how long it'd take me. There's no real context switch if you do it immediately after the PR.
>Besides if all I’m doing is taking 30 second to copy and paste something what value is that really adding?
Are you a GPT-3 bot? I've answered this three times.
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 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...
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.
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?
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.
> 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.
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.
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?"
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?
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.
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 PR? Whatever you'd write in the ticket you can just write there instead of splitting information between two places.