Comment by zo1

Comment by zo1 10 months ago

Most official documentation is awful, and just an API reference. It's (almost) like asking someone to learn english and then pointing them to a dictionary.

And that's because a lot of devs think it's perfectly dandy to just put perfunctory docstrings in their methods, point it at whatever "doc generation" tool, wire it up to a github.io domain and call it a day.

There is a reason people crave, want and seek things like SO and blog-posts. They're packed full of insight, working examples and just plain old "how TF do you use this thing". Oh and of course, the "this problem A didn't work when using setup B and C, and that's because of reasons X,Y,Z. Here, try H,I & K and it'll work.

yunwal 10 months ago

> Most official documentation is awful

This goes doubly so for google cloud documentation. Firebase docs are decent, but if you're a developer who's gotten used to google's documentation style I could see skipping right over it.

Reply View 1 reply

com2kid 10 months ago

For many years entire sections across multiple pages of firebase's documentation were missing after the site contents had been migrated from one system to another.
Multiple years of sample code and examples just cut out from the middle of pages.
When I was building on firebase it took me a long time to reconstruct exactly how certain aspects of the system were supposed to work just because of those missing docs.

Reply View | 0 replies

netdevnet 10 months ago

That's true but people still do it for well documented stuff like Vue, Svelte and the R that shall not be named. Two wrongs that don't make a right

Reply View 0 replies

macintux 10 months ago

I remember writing a Twitter library when that was a thing, and being severely disappointed at the quality of the API documentation. There seemed to be little choice other than to experiment to see what responses you’d receive (and hope that it wouldn’t change underneath you). Same was often true with some of the GitHub APIs, although it’s been a few years since I’ve spent time with them.

Reply View 0 replies