Ask HN: What are the most popular libraries with the crappiest documentation?
By bad documentation I mean - improper structure, too cryptic for a beginner or not legible.
55 comments
Solr, and SolrJ in particular. Personally I find googling for 3rd party examples / tutorials / stackoverflow posts much more productive than reading the Solr documentation.
boost
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.
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.
OpenSSL by far.
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/
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.
It's not perfect but it's way better than most libraries so I wouldn't count it.
The search function on jQuery documentation makes me want to pull my hair out.
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.
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 "vertical" = child elements are underneath each other.
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 "vertical" = child elements are underneath each other.
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
Caffe
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.
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.
And why would you document that? It's not like it's one of the most common implementation mistakes to handle IVs incorrectly.
> They've actually been doing great work on the code
It still is nowhere near readable.
It still is nowhere near readable.
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.
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
All 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!
The CloudFormation docs seemed to have been intentionally designed to torture anyone trying to use it. You end up reading everything you can find, learning almost nothing and having to infer everything from whatever examples you can find combined with just straight up guessing. Guessing with a run/teardown feedback loop measured in minutes with very little feedback.
Same with VMware apis
Visual Basic for Applications.
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.
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".
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".
Caffe
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.
* 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.
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.
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.
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.
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.
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
[0] https://docs.scipy.org/doc/numpy-1.12.0 [1] https://matplotlib.org/contents.html
PostgreSQL has very thorough and well-written documentation.
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.
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.
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.
SQLAlchemy docs are very good. I remember having to drop two layers of abstraction under the main API to get some very specific stuff done and it was still documented with useful example code.
The actual software design is great as well, single-handedly changed my mind about ORMs.
The actual software design is great as well, single-handedly changed my mind about ORMs.
I think TeX came pretty close.
I think the Exim spec is pretty much the gold standard for reference documentation, but they need a separate user-friendly introduction too (there was a separate paper book at one point).
I think the Exim spec is pretty much the gold standard for reference documentation, but they need a separate user-friendly introduction too (there was a separate paper book at one point).
Laravel is always praised for its documentation: https://laravel.com/docs/
I've heard that every comment in code follows the same pattern: every line becomes smaller and smaller. There is a lot of dedication in this project.
I've heard that every comment in code follows the same pattern: every line becomes smaller and smaller. There is a lot of dedication in this project.
This beautiful-docs repo has a list of higher quaility docs...
https://github.com/PharkMillups/beautiful-docs
https://github.com/PharkMillups/beautiful-docs
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.
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.
If you are writing starting a project or writing it for yourself, this is great advice.
If you aspire to have it used by other people, it is still good advice, but only a first step. The next step is to test the documentation. Have someone run through your intro tutorial and see both:
- How hard is the tutorial to work through
- How well does it help them build a mental model of the major interfaces of the project.
If you aspire to have it used by other people, it is still good advice, but only a first step. The next step is to test the documentation. Have someone run through your intro tutorial and see both:
- How hard is the tutorial to work through
- How well does it help them build a mental model of the major interfaces of the project.
RabbitMQ, very easy to start in any language you'd want.
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.
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.
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/ - a couple of high level diagrams, and links to headers.
Just look at this: https://webrtc.org/native-code/native-apis/ - a couple of high level diagrams, and links to headers.
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.
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
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 :)
I'm sure the docs were great, but I didn't get much chance to peruse them :)
Have you ever heard of this ridiculous idea of using offline documentation?
Pick a JavaScript library. Odds are its documentation is going to be frustratingly inadequate. Some (e.g., Ramda) are quite nice. Many are crap.
Moment.js is good, I understood everything with basic JS knowledge and coming from python
Vuejs.org is probably the best documentation I have seen
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.
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".
This, absolutely. It's pretty dreadful.
Jasmine
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
I found Microsoft's Office JS API docs to be terrible and borderline unusable.