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".
Ask HN: What are the most popular libraries with the crappiest documentation?
41–50 of 56 posts
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#42On the flip side, does anyone you examples of projects with perfect documentation?
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.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#43OpenCV, 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.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#44Jasmine
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
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#45I found Microsoft's Office JS API docs to be terrible and borderline unusable.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#46OpenSSL 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.
> They've actually been doing great work on the code 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.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#47On 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.
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.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#48On the flip side, does anyone you examples of projects with perfect documentation?
RabbitMQ, very easy to start in any language you'd want.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#49Maybe 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/
The search function on jQuery documentation makes me want to pull my hair out.
Re: Ask HN: What are the most popular libraries with the crappiest documentation?
#50Pick a JavaScript library. Odds are its documentation is going to be frustratingly inadequate. Some (e.g., Ramda) are quite nice. Many are crap.
Vuejs.org is probably the best documentation I have seen