Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: What are the most popular libraries with the crappiest documentation?

news.ycombinator.com

Post reply on HN
Print view View original

21–30 of 56 posts

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#21

Post by pritambarhate »

GlennS wrote: post #19

Maven. They've clearly gone to quite some effort to document it thoroughly. Yet whenever I have to read any of it my brain rebels and my eyes just slide off. I think it may be a case of just too much jargon. It's probably also because Maven problems are not the fun kind of problems, but rather the irritating kind. Whenever I'm trying to figure out how to make it do something it's because Maven has gotten in the way o…

Yes, after using Maven for so many years, I also find it very hard to understand Maven documentation. In the end, I have to depend on code samples from tutorials and trial and error to figure out stuff.

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#23

Post by moron4hire »

WebRTC is very poorly documented, especially considering how well most of the other Web APIs are documented. There are lots of tutorials with example in the wild that are now outdated. The rare bit of up-to-date documentation only show the most basic usage. And nobody has any idea how to trap, handle, and recover from errors.

Samesies for every wireless communication protocol I've used. ZWave, Zigbee, Bluetooth. Anything written by electrical engineers tends to be completely inadequate for software.

I find Ember and Angular's documentation to be infuriating. Ember is so incomplete, and Angular is so infantile. React in comparison is so well documented, but then there isn't a lot to document.

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#24

Post by synthmeat »

Socket.io.

Magic methods with aliases sprinkled everywhere. Configuration parameters passed here or there, no one knows where. Initialization in a million ways, through using 3rd party frameworks (like express).

And for all that, there's few small pages of documentation, very badly formatted.

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#25

Post by codefined »

synthmeat wrote: post #24

Socket.io. Magic methods with aliases sprinkled everywhere. Configuration parameters passed here or there, no one knows where. Initialization in a million ways, through using 3rd party frameworks (like express). And for all that, there's few small pages of documentation, very badly formatted.

I remember when their server documentation was down and

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#26

Post by bluejekyll »

mamazaco wrote: post #22

On the flip side, does anyone you examples of projects with perfect documentation?

If this wasn't sarcastic, it probably should have been.

There is no perfect documentation, because you can't predict your audience. I document code in such a way as to make it easier for myself to go back to it. I've kicked myself too many times to count where I didn't document something; went back to code, found it confusing, went to find out who wrote it only to discover it was me.

Document your code for yourself.

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#27

Post by x0 »

mamazaco wrote: post #22

On the flip side, does anyone you examples of projects with perfect documentation?

I really like the way (most of) PHP is documented. Every function gets a page, most of those pages get usage, examples and comments. However, when you go into some of the more obscure stuff, the documentation tends to just be function prototypes. So not perfect but I really enjoy it.

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#29

Post by willvarfar »

This is not quite in the spirit of the question, but I want to vent anyway ;): I was working in LLVM a few months ago and it suffered from the most curiously amateur illegibility problem: every morning (which is the middle of the night in the US), the documentation was deleted and regenerated, which took several hours and meant that during my work day the docs were offline! Had they not thought to generate the docs in a new folder and swap a symlink when done? :)

I'm sure the docs were great, but I didn't get much chance to peruse them :)

Re: Ask HN: What are the most popular libraries with the crappiest documentation?

#30

Post by mattip »

mamazaco wrote: post #22

On the flip side, does anyone you examples of projects with perfect documentation?

NumPy [0] and matplotlib [1] both have well designed tutorials, specific function documentation, and integration with IDEs for Intellisense help while programming.

[0] https://docs.scipy.org/doc/numpy-1.12.0 [1] https://matplotlib.org/contents.html

Post reply on HN