Document, document and document

This is a follow up on my It all comes down to one thing - whether it gets the job done...

Like I said in my original post, the ruby net-ldap package didn't work for me. Couple of days after that, I had the interest to go back, and gave another try. In the end, I was able to make the ruby code work, and it all came down to one thing: document - the document for the ruby package wasn't accurate, and some method didn't do exactly what the document claimed.

Graham Barr did a great job, not only in the sense that his library worked and it was pretty OO, but also his library was well documented and there were plenty of examples came with the document.

As for the ruby library, I went back and checked it's history, appearantly it just got a group of new maintainers (or probably a single new maintainer). I suspect that the document was not a priority for them (not yet).

As a general observation, there are lots can be done to improve ruby document, even the document for the language itself.

Again, Graham Barr did do a good job on documentation!

Peter (Guo) Pei

Comment on Document, document and document

Replies are listed 'Best First'.
Re: Document, document and document by toolic (Bishop) on Nov 07, 2010 at 20:07 UTC
and some method didn't do exactly what the document claimed. So, you submitted a patch to fix the documentation error, right? All I know about Ruby is what I just googled, and it claims to be open source. As a general observation, there are lots can be done to improve ruby document, even the document for the language itself. And, you've alerted the good folks who maintain Ruby about your specific suggestions for improvements, right?	[reply]
Re^2: Document, document and document by PeterPeiGuo (Hermit) on Nov 07, 2010 at 20:31 UTC
As for the question about the package, absolutely. As for the language, the ruby community as a whole is working very hard to improve the documentation, and as one can see, it is getting better over the time. Peter (Guo) Pei	[reply]
Re: Document, document and document by locked_user sundialsvc4 (Abbot) on Nov 08, 2010 at 14:37 UTC
The same can certainly be said of the CPAN library. I think that the Ruby community is every bit as good as the Perl community on this score, and of course, there are some folks who are active contributors in both. Technical prowess is really not a point-of-issue here. Documentation is very often better when it is contributed by someone other than the author(s), because it better reflects the POV of the user ... something that is much harder for authors to see because they have been so immersed in the problem by virtue of building (and then, publishing) a solution for it.
Re: Document, document and document by andal (Hermit) on Nov 12, 2010 at 13:23 UTC
Actually, I've tried to use python and ruby and the main reason why I still use perl is the documentation. More precisely, the convenience and fullness of documentation in perl. So, it's not only Graham Barr, it's all of perl creators :)	[reply]