7 ms·
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.
- devnonymous 9y agoThe 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.
- hnuser1706 9y agoOpenSSL by far.
- Fannon 9y agoMaybe 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 9y agoWas 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.
- baby 9y agoIt's not perfect but it's way better than most libraries so I wouldn't count it.
- kevans91 9y agoThe search function on jQuery documentation makes me want to pull my hair out.
- douche 9y agoMaybe 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.
- anotheryou 9y agoAndroid 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 9y agoOne 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
- curiousgal 9y agoCaffe
- guidovranken 9y agoOpenSSL 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.
- dom0 9y agoI 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.
- baby 9y ago> They've actually been doing great work on the code It still is nowhere near readable.
- dom0 9y agoTo 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.
- rsln-s 9y agoA 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
- di4na 9y agoAll the AWS stuff.
- tejinderss 9y agoSame with VMware apis
- jalfresi 9y agoAgreed, 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!
- freshhawk 9y agoThe 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.
- lucb1e 9y agoVisual Basic for Applications.
- ikari_pl 9y agoThe 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 9y agoOh 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".
- nmca 9y agoCaffe
- probably_wrong 9y agoThe 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.
- GlennS 9y agoMaven. 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 9y agoYes, 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.
- rm_-rf_slash 9y agoOpenCV 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.
- mamazaco 9y agoOn the flip side, does anyone you examples of projects with perfect documentation?
- bluejekyll 9y agoIf 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.
- afarrell 9y agoIf 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.
- x0 9y agoI 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.
- swashbuck1r 9y agoThis beautiful-docs repo has a list of higher quaility docs... https://github.com/PharkMillups/beautiful-docs https://github.com/PharkMillups/beautiful-docs
- mattip 9y agoNumPy [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 https://docs.scipy.org/doc/numpy-1.12.0 [1] https://matplotlib.org/contents.html https://matplotlib.org/contents.html
- moron4hire 9y agoWebRTC 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 9y agoWebRTC 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.
- synthmeat 9y agoSocket.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 9y agoI remember when their server documentation was down and
- willvarfar 9y agoThis 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 9y agoHave you ever heard of this ridiculous idea of using offline documentation?
- bitwize 9y agoPick a JavaScript library. Odds are its documentation is going to be frustratingly inadequate. Some (e.g., Ramda) are quite nice. Many are crap.
- kyleperik 9y agoVuejs.org is probably the best documentation I have seen
- BrandoElFollito 9y agoMoment.js is good, I understood everything with basic JS knowledge and coming from python
- baby 9y agoI remember having enormous difficulties developing an audio app with HTML5. I don't know if they made more progress but almost nothing was documented.
- hprotagonist 9y agoOpenCV, 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 9y agoThis, absolutely. It's pretty dreadful.
- sudo_bangbang 9y agoJasmine 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
- indexerror 9y agoI found Microsoft's Office JS API docs to be terrible and borderline unusable.
- gorbachev 9y agoSolr, and SolrJ in particular. Personally I find googling for 3rd party examples / tutorials / stackoverflow posts much more productive than reading the Solr documentation.
- xixor2 9y agoboost