3 ms·
It’s so abundantly clear that most documentation writers at google have NEVER used their own products in production (nor do they ever intend to). This is how I
by tmpz22 7y ago
It’s so abundantly clear that most documentation writers at google have NEVER used their own products in production (nor do they ever intend to).
This is how I imagine their meetings to discuss this goes:
“Users leave our documentation pages in under 15 seconds! Our documentation is so clear and efficient! For some reason their hardware analytics show that the device falls 20 meters and shuts down afterwards, but that is surely an unrelated event!”
- hyperdimension 7y agoYet another A/B testing success story! And if they spend a lot of time poring over our documentation, well, that just means our user engagement is through the roof!
- obmelvin 7y agoGranted I've not used a ton of AWS services because all of this was in context of grad school research, but I've found this with a lot of the AWS documentation I've come across. Things like documentation for general API being inconsistent with language specific library docs, or function signature is different than what docs indicate. I had issues with others, but for reference this was largely with MTurk JS bindings to the api.
- tmpz22 7y agoFWIW I’ve also worked with mturk and find that to be an unfair comparison point because it basically a vestigial organ that nobody in academia actually even uses correctly.
- obmelvin 7y agoI have no idea how much mturk makes, my guess is not a ton and its mostly in a maintenance mode? Would explain the state of the documentation. Not sure I see how researchers improper utilization of crowdsourcing is a reason for the API documentation to be inaccurate (and I don't think even updated after I emailed while I was still using the docs).
- anongraddebt 7y agoNot sure if they used it correctly or not, but a good friend who recently finished his Phd at an elite department used MTurk heavily for surveys.
- verst 7y agoHonestly most techdoc writers have never really used their products in production. You are lucky if they have built their own test and sample apps. So the solution is having the engineers building the service write the documentation right? Wrong. They also don't know what assumptions a real customer makes and how they would use it. Quite likely they too don't understand real external production use. Writing technical documentation is hard.
- Ididntdothis 7y ago"Writing technical documentation is hard." So true. Good documentation can make or break a platform. I think a big part of the success of C++ is that Stroustrup is an excellent writer. A lot of the posts I have seen from Linus were also very well written. In the 90s Apple had documentation that seemed written by people who actually knew how to develop software. Nowadays it feels less so.
- thu2111 7y agoIt's much easier to get platform developers to write sample apps using their own platform than it is to get techdoc writers to do so though.