News for hackers. Stuff that matters.
Re:Things People Hate about Your Open Source Docs by cobrausn on Friday June 21, 2013 @11:36AM (#5918532)
Of course, your examples shouldn’t just be brief two-line snippets. As Rich Bowen of the Apache project puts it, “One correct, functional, tested, commented example trumps a page of prose, every time.”

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

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.