> 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.
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.
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.
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.
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.