4 ms·

On documentation: I've seen dozens of articles on this site about hiring practices from large technical companies, and Google in particular. I don't remember

On documentation: I've seen dozens of articles on this site about hiring practices from large technical companies, and Google in particular. I don't remember seeing anything suggesting they even verify that the people they're hiring are capable of writing basic documentation, let alone that they appreciate the importance of it being complete, correct, and up to date. Every indication is that Google vastly undervalues documentation, both for internal and external purposes.

MattGaiser 6y ago
> Every indication is that Google vastly undervalues documentation, both for internal and external purposes. This just seems to be companies as a whole. Documentation is a low-status activity (no promotions or raises available for doing it) that still requires decent cognitive function, so it is not something you want to do when you are energized and ready to go nor something you can do when tired and not in the mood to work. There are no automated tests to tell you that the documentation no longer works, so the engineers would need to periodically check. We have automated tests in code because engineers won't comprehensively check everything. In my org we frantically document when an engineer gives notice. Otherwise, we can't even keep the URLs updated or maintain a running list of configuration variables.
- mjw1007 6y ago
  There's a virtuous circle with documentation: if you start with something that's complete and correct, then when you make a change which is visible to the code's clients you can go and change the documentation in the same patch series, and check that this happens as part of the main code review. Digging yourself out of the hole where your documentation is already wrong or incomplete is much harder: when you go to describe a change you might find that the thing you're changing isn't mentioned, or is described wrongly, or there is no terminology for the thing you need to talk about. So you need everyone to take care that standards don't slip, which is why it's important to make the importance of documentation part of the company culture, and make sure every programmer is capable of doing their bit.
- gfxgirl 6y ago
  There's a startup idea there. Be the company that makes excellent docs. Get all the other companies to pay your company to make and maintain their docs.
- coredog64 6y ago
  I don’t know about that. At my last employer we had one guy on DevRel and a big part of his job was making sure we had good documentation. When other teams complained, we first checked to see if the docs were good: If they were, we pointed them to the docs. If the docs were wrong, confusing, out-of-date or missing we’d apologize and fix the docs. He didn’t get a promotion, but he did have a lot of positive visibility. When there was a round of layoffs, other teams lost engineers but we got to keep him.
ThrowawayR2 6y ago
> "I don't remember seeing anything suggesting they even verify that the people they're hiring are capable of writing basic documentation" Large companies hire technical writing specialists to do documentation, not software developers.

MattGaiser 6y ago

> Every indication is that Google vastly undervalues documentation, both for internal and external purposes. This just seems to be companies as a whole. Documentation is a low-status activity (no promotions or raises available for doing it) that still requires decent cognitive function, so it is not something you want to do when you are energized and ready to go nor something you can do when tired and not in the mood to work. There are no automated tests to tell you that the documentation no longer works, so the engineers would need to periodically check. We have automated tests in code because engineers won't comprehensively check everything. In my org we frantically document when an engineer gives notice. Otherwise, we can't even keep the URLs updated or maintain a running list of configuration variables.

mjw1007 6y ago
There's a virtuous circle with documentation: if you start with something that's complete and correct, then when you make a change which is visible to the code's clients you can go and change the documentation in the same patch series, and check that this happens as part of the main code review. Digging yourself out of the hole where your documentation is already wrong or incomplete is much harder: when you go to describe a change you might find that the thing you're changing isn't mentioned, or is described wrongly, or there is no terminology for the thing you need to talk about. So you need everyone to take care that standards don't slip, which is why it's important to make the importance of documentation part of the company culture, and make sure every programmer is capable of doing their bit.
gfxgirl 6y ago
There's a startup idea there. Be the company that makes excellent docs. Get all the other companies to pay your company to make and maintain their docs.
coredog64 6y ago
I don’t know about that. At my last employer we had one guy on DevRel and a big part of his job was making sure we had good documentation. When other teams complained, we first checked to see if the docs were good: If they were, we pointed them to the docs. If the docs were wrong, confusing, out-of-date or missing we’d apologize and fix the docs. He didn’t get a promotion, but he did have a lot of positive visibility. When there was a round of layoffs, other teams lost engineers but we got to keep him.

ThrowawayR2 6y ago

> "I don't remember seeing anything suggesting they even verify that the people they're hiring are capable of writing basic documentation" Large companies hire technical writing specialists to do documentation, not software developers.