7 ms·

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 4y ago
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_ 4y ago
  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 4y ago
    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.
    - carlisle_ 4y ago
      At this point you’re just strawmaning.
    - malermeister 4y ago
      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. Where was the value created again?
      - sanderjd 4y ago
        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).
        malermeister 4y ago
        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.
- sanderjd 4y ago
  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 4y ago
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?
- carlisle_ 4y ago
  Can you explain why it’s necessary I need to write a ticket to update documentation?
  - treis 4y ago
    I did. To give your team visibility into what you're doing and why.
    - carlisle_ 4y ago
      And the PR doesn’t do that?
      - treis 4y ago
        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.
        carlisle_ 4y ago
        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.

mr-ron 4y ago

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_ 4y ago
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 4y ago
  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.
  - carlisle_ 4y ago
    At this point you’re just strawmaning.
  - malermeister 4y ago
    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. Where was the value created again?
    - sanderjd 4y ago
      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).
      - malermeister 4y ago
        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.
sanderjd 4y ago
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 4y ago

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?

carlisle_ 4y ago
Can you explain why it’s necessary I need to write a ticket to update documentation?
- treis 4y ago
  I did. To give your team visibility into what you're doing and why.
  - carlisle_ 4y ago
    And the PR doesn’t do that?
    - treis 4y ago
      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.
      - carlisle_ 4y ago
        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.