> First, no one has the discipline to write much of anything down.
This is why it's baked into the company culture. It's very common for someone to ask where something is in the handbook or if an issue has been created for something.
> It's a very boring process and it's always going to be low-resolution. Your most meticulous documentation writers will get fired for failing to get their "real work" done. If you personally recognize the value of the documentation they furnish and thus refuse to fire them, all of their peers will feel that they are dead weight, which is still a ticket out of the company.
Fwiw, everyone is responsible for maintaining the handbook/our process and procedure documentation. The docs team isn't on the hook for it, nor is it the sole responsibility of engineering.
> Second, after all that work, no has the discipline to read much of anything that you've written!
After enough reminders, you'd be amazed at how quickly people learn to RTFM at work.
> They skim. They glance. They Ctrl+F. They don't read. When you're in a pickle and you can pick out a life-saving bit of documentation, it's amazing, but that happens quite rarely and requires a lot of energy.
It's true that people skim the handbook (the guide with all of the "Here's how you get access to Twitter accounts" stuff), but runbooks are actually looked at when stuff hits the fan. I think it's important to differentiate these two things since they have different purposes. Imo runbooks should be as lean as possible for that very reason.
> Good programmers are both lazy and dumb!
This level of documentation is helpful for non-developers who make up a significant part of many organizations. We're not just talking about documenting code here.
> If you want documentation that means something, it needs to be part of the process of actually working.
> Fwiw, everyone is responsible for maintaining the handbook/our process and procedure documentation. The docs team isn't on the hook for it, nor is it the sole responsibility of engineering.
I find that in practice, with non-mission-critical activities, especially documentation, when everyone is responsible for getting it done (And making it useful), no-one is.
This is why it's baked into the company culture. It's very common for someone to ask where something is in the handbook or if an issue has been created for something.
> It's a very boring process and it's always going to be low-resolution. Your most meticulous documentation writers will get fired for failing to get their "real work" done. If you personally recognize the value of the documentation they furnish and thus refuse to fire them, all of their peers will feel that they are dead weight, which is still a ticket out of the company.
Fwiw, everyone is responsible for maintaining the handbook/our process and procedure documentation. The docs team isn't on the hook for it, nor is it the sole responsibility of engineering.
> Second, after all that work, no has the discipline to read much of anything that you've written!
After enough reminders, you'd be amazed at how quickly people learn to RTFM at work.
> They skim. They glance. They Ctrl+F. They don't read. When you're in a pickle and you can pick out a life-saving bit of documentation, it's amazing, but that happens quite rarely and requires a lot of energy.
It's true that people skim the handbook (the guide with all of the "Here's how you get access to Twitter accounts" stuff), but runbooks are actually looked at when stuff hits the fan. I think it's important to differentiate these two things since they have different purposes. Imo runbooks should be as lean as possible for that very reason.
> Good programmers are both lazy and dumb!
This level of documentation is helpful for non-developers who make up a significant part of many organizations. We're not just talking about documenting code here.
> If you want documentation that means something, it needs to be part of the process of actually working.
100%, this is the only way it works.