Hacker News Reader

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.

View on HN

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

Reply on news.ycombinator.com