News for hackers. Stuff that matters.
Re:The Blind Men and the Elephant: A Story of Noobs by jwhite on Tuesday February 09, 2010 @11:46PM (#1114237)
I'm starting out in Ruby the last couple of months, but I've done a lot of Python, among other things. I've read other people criticizing the poor standard of documentation of some parts of Ruby and Ruby libraries, and from my recent experiences, I can sympathize. But as a maintainer of an open source library, I can also sympathize with the feeling that documentation always seems like a lower priority compared with new features.

Recently I've been getting a lot of user support requests that have made me realize I have to lift my own game when it comes to documentation. It is worth remembering that the 'Laziness' component of 'Laziness, Impatience, Hubris', includes a healthy dose of documentation:

"Laziness: The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful, and document what you wrote so you don't have to answer so many questions about it. Hence, the first great virtue of a programmer."

From http://c2.com/cgi/wiki?LazinessImpatienceHubris, quoting Larry Wall.

I found that to be good motivation.

EDIT: Also, API documentation isn't enough for new users. As the article points out, users need to be taught the basic concepts to know they are dealing with an elephant, not a snake. Without the basics it is hard to ask intelligent questions.

There are no comments on this comment yet.