
Ask HN: What are the most popular libraries with the crappiest documentation? - shivam_mani
By bad documentation I mean - improper structure, too cryptic for a beginner or not legible.
======
anotheryou
Android when you go one level deeper than the most high-level api. It's easy
to record a file with AudioRecord(), but getting the audio stream to handle
some analysis yourself is way harder. I'm not the best android programmer and
had to read the C code underneath to get to the stuff below the
"MediaRecorder".

Oh and Android design standards and best practices... Nobody tells you which
stuff is outdated and that you need to use compatibility stuff by default to
keep things working on more devices etc... Also no technical description on
how to implement Material Design at all and some quirky problems are really
common (e.g. negative margin on a button, easy in html/css, but impossible
that way in Android).

edit: my new favourite android fuck-up though is having the icons for
horizontal and vertical layouts swapped:
[http://i.imgur.com/xJ1ODI3.png](http://i.imgur.com/xJ1ODI3.png) "vertical" =
child elements are underneath each other.

~~~
wasyl
One recurring theme with Android documentation is also showing example usages
for the absolutely simplest, most straightforward cases - once you try
implementing this in a real app, it turns out things are way more complex

------
guidovranken
OpenSSL 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.

~~~
baby
> They've actually been doing great work on the code

It still is nowhere near readable.

~~~
dom0
To this day I have no idea where the EVP factories are defined (the symbols
aren't in the tree)... I suspect that they are probably automatically
generated, but I haven't found a separate script that does it, so it might be
some CPP stuff in some well-hidden file.

------
probably_wrong
The 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.

------
Fannon
Maybe 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/](http://devdocs.io/)

~~~
mgkimsal
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.

------
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.

~~~
mort96
WebRTC for the browser is poorly documented, but try their C++ library. The
documentation is _literally_ "it's open source, to look st headers in the api/
directory".

Just look at this: [https://webrtc.org/native-code/native-
apis/](https://webrtc.org/native-code/native-apis/) \- a couple of high level
diagrams, and links to headers.

------
hprotagonist
OpenCV, particularly the python bindings. Return values are not specified or
only alluded to, a complete function listing is normally absent. You kind of
have to piece it together from the (Only slightly better) c++ docs and the
awfully written "tutorials".

~~~
expenses
This, absolutely. It's pretty dreadful.

------
GlennS
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 of the thing I
actually want to be doing.

~~~
pritambarhate
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.

------
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 :)

~~~
dozzie
Have you ever heard of this ridiculous idea of using _offline_ documentation?

------
di4na
All the AWS stuff.

~~~
jalfresi
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!

------
ikari_pl
The 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.

~~~
freshhawk
Oh man, what a blast from the past. I remember those docs, they seemed so
promising at first glance. But everything was just subtly slightly wrong.

Those libraries were fantastic, so far ahead of the rest of the pack at the
time in terms of API design and code quality. I remember looking at it and
being so happy to see that there was a js utility/cross-browser library
written by _engineers_ thinking in terms of software rather than "scripts".

------
rsln-s
A lot scientific libraries have virtually non-existent documentation (often
just a bunch of html generated by Doxygen). NetworKit is one example, but it
applies to way too many of them. Caffe is another example mentioned below

------
douche
Maybe not the most popular, but the Microsoft UCWA documentation is atrocious.
Really, anything surrounding Lync/Skype for Business - so much of it is
undocumented, and what is documented is often incorrect.

------
bitwize
Pick a JavaScript library. Odds are its documentation is going to be
frustratingly inadequate. Some (e.g., Ramda) are quite nice. Many are crap.

~~~
BrandoElFollito
Moment.js is good, I understood everything with basic JS knowledge and coming
from python

------
sudo_bangbang
Jasmine
[https://jasmine.github.io/2.0/introduction.html](https://jasmine.github.io/2.0/introduction.html)
Documentation could be structured in a much better way making it the things
you need easier to find. I always end up searching the whole page

------
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.

~~~
codefined
I remember when their server documentation was down and

------
gorbachev
Solr, and SolrJ in particular. Personally I find googling for 3rd party
examples / tutorials / stackoverflow posts much more productive than reading
the Solr documentation.

------
rm_-rf_slash
OpenCV 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.

------
baby
I remember having enormous difficulties developing an audio app with HTML5. I
don't know if they made more progress but almost nothing was documented.

------
indexerror
I found Microsoft's Office JS API docs to be terrible and borderline unusable.

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

~~~
perlgeek
PostgreSQL has very thorough and well-written documentation.

~~~
petepete
Like with everything the PostgreSQL project creates, the documentation feels
comprehensive, authoritative and solid. It's always my first port of call if I
have a question.

The one thing I'd like to see is more examples. Sometimes a quick demo of a
function is all that's required for basic use.

------
lucb1e
Visual Basic for Applications.

------
curiousgal
Caffe

------
hnuser1706
OpenSSL by far.

------
xixor2
boost

------
nmca
Caffe

------
devnonymous
The chances that you'd get responses to your question would be higher if you
explained why you're asking the question.

Also, I doubt there are any popular libraries with ^crappy^ documentation. why
even use such a strongly negative word?... Disagree that it is strongly
negative? Well I think your question is crappy.

