Hacker News Reader

Comment by mft_ | Hacker News Reader

I'm glad that Google is thinking along these lines - as an amateur coder, I often find the UX of some of their products (e.g. AppEngine, YouTube API) terrible, often related to documentation not actually being comprehensive enough.

And further, if only the Pandas team would also think about this a little more - surely the most frustrating, least intuitive module I've ever had the misfortune to encounter in Python.

View on HN

I often joke how google's documentation is the perfect example of documentation written by geniuses / very smart people. Often you find the way the API is designed more complex than it should/could be, and documentation missing to things that might not be so obvious for everyone. Google maps is also a good example of such API that has a stiffer-than-required learning curve imo.

Angular 2/4 probably fits in the very smart people category :)

I'd expect documentation-only-for-very-smart-people to be complete, correct, and rigorous, but lacking in examples, rationale, and perhaps organisation.

That's not at all what I see in the documentation for Google's public libraries and frameworks.

This phenomena seems more like, uhh, forgetting that lots of people haven't built the mental framework that makes things obvious to you. Not sure how else to describe it. Like, it'll just assume a lot of detailed knowledge as just something that everyone easily gets, and the very specific system they built on top of it is the only thing that needs to get documented.

For all that I love Datomic, their docs are a particularly egregious example of this, IMO. See: http://docs.datomic.com/query.html

Curse of Knowledge https://en.wikipedia.org/wiki/Curse_of_knowledge

While this is true, I've found the UI for AWS to be much, much worse. And that's across basically all of their products.

>surely the most frustrating, least intuitive module I've ever had the misfortune to encounter in Python.

Interesting... I've had the complete opposite experience. I've found it to be pretty intuitive and easy to use. Some of the documentation could certainly be better.

Reply on news.ycombinator.com