Re:Things People Hate about Your Open Source Docs
by Apreche on Friday June 21, 2013 @02:36PM
(#5920058)
This is 100% true. I am constantly frustrated by incomplete code examples in documentation. The one thing in particular that bothers me the most are when Python snippets don't show the import statements.
do_magic(param, other_param)
Where do I import do_magic from?!?!
Re:Things People Hate about Your Open Source Docs
by Cyranix on Friday June 21, 2013 @03:45PM
(#5920507)
Same thing in Java -- if there's a class named something commonplace like "Transaction" or "Connection", it's going to be pretty critical to understand whose implementation that refers to.
Re:Things People Hate about Your Open Source Docs
by kamjam on Friday June 21, 2013 @04:28PM
(#5920786)
Same in .Net, although Resharper (http://www.jetbrains.com/resharper/) has made my life a lot easier by giving me much better import/using suggestions, although not 100% foolproof.
Re:Things People Hate about Your Open Source Docs
by angersock on Friday June 21, 2013 @01:15PM
(#5919445)
The Three.js project has really shit documentation for most things, but they have scrupulously-maintained examples for their library which serve to answer most questions.
Re:Things People Hate about Your Open Source Docs
by general_failure on Friday June 21, 2013 @01:56PM
(#5919772)
Care to give a few examples of where three.js docs are lacking?
Re:Things People Hate about Your Open Source Docs
by angersock on Friday June 21, 2013 @04:58PM
(#5920951)
Just a bunch of todos for the semi-auto-generated stuff, lots of missing information about how the whole thing fits together. Not clear what is core functionality and what is well-maintained extensions for the examples (OBJ loader, etc.)
It's a great library, don't get me wrong--just not the docs I'm looking for. I've been meaning to contribute back to help with this issue.
If HN allowed signatures, that quote would be mine. I grok libraries and other people's code so much faster when I have a good working example, and the mere existence of that example makes me 10x more likely to use the lib (or, when I have no other option, 10x more likely to complain less).