Visual Basic for Applications.
Ask HN: What are the most popular libraries with the crappiest documentation?
11–20 of 56 posts
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#12The contents of this comment might be very outdated, but still... I remember working with the Dojo and Dijit JS libraries around 8 years ago. They were really great, high quality code, very well structured and designed... Except the documentation wasn't always clear, the examples online were for the older versions of the libraries (not fully compatible), and — my favorite and biggest pain — even the examples on Dijit page often didn't work. The code didn't work when you used it and the interactive demos threw an error as well. So getting it right was a matter of trial and error.
And still I think the libraries as they were, were great.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#13All the AWS stuff.
Same with VMware apis
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#14OpenSSL is rather inscrutable. They've actually been doing great work on the code and I'd say it's pretty secure now. But the documentation is still a mess. I recently had to resort to inferring the correct way to do something with OpenSSL by looking at how OpenSSL itself deals with that particular task + extensive testing, because documentation on certain operations appeared to be absent. No bueno.
I audited once whether an application was using nonces the correct way with libcrypto of OpenSSL. Suffice to say, that wasn't documented at all (I think it still isn't); in the end I dug through the implementation and wrote my own tests as well. Seems to be more common than I thought.
And why would you document that? It's not like it's one of the most common implementation mistakes to handle IVs incorrectly.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#15Caffe
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#16The TensorFlow tutorials are terrible for a library this popular. Two specific instances that bit me this week:
* The RNN tutorial is just a code dump, with barely any comments. And since it implements some state-of-the-art network, it has several optimizations that are guaranteed to drive a beginner crazy.
* Their seq2seq tutorial doesn't run anymore due to API changes. Their official reply (for months now) is "we are writing a new tutorial, so wait until we are done".
I fought (and lost) for switching libraries based on how bad the tutorials are, which is literally the opposite of what you'd want a tutorial to achieve. You can't get worse than that.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#17All the AWS stuff.
Agreed, the AWS docs are terrible; they waffle on about inconsequential stuff, and insist on detailing every step and side tangent. Just tell me how to get postfix/php to use SES email without is failing silently!
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#18Maybe it's just me, but I never got around liking the jQuery documentation. Its not bad - but visually too heavy, not easy to navigate and the example code is often not very consistent. Counterexample: The lodash documentation. Sidenote: A very nice project that aggregates many API documentations and puts them into a coherent style and nice UX is http://devdocs.io/
Was just talking to a colleague about how the visual presentation of docs affects my view of projects, and I bet it has an impact on many others as well. Poor visual/ux on docs probably turns me off using a project even more than no docs.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#19Maven.
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 of the thing I actually want to be doing.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#20OpenCV could definitely use some work. If Stack Overflow didn't exist I don't know how anyone could go from the OpenCV documention to a project without a steep uphill climb.