Our documentation sucksby jimt (Chaplain)
|on Apr 12, 2007 at 21:31 UTC||Need Help??|
First of all, I will lead with my standard disclaimer and say that I am thoroughly, thoroughly, hopelessly guilty of this as well. So I'm also yelling at myself. I have some half though out ideas, but am mainly just waxing philosophic.
In short, I think our documentation sucks. "Our" can be interpreted as desired - the perl community, the open source world, IT in general. I think everybody's guilty.
I also think this is the biggest stumbling block to the use of code. Everybody always preaches that code should be re-used - use the standard libraries, use the stuff on CPAN, use the existing neato toolkit. It's better that writing your own, there are other solutions, blah blah blah blah.
The problem is, a lot of the time, it's easier to write your own solution than to try to decipher the documentaiton on an existing solution. Sure, it might solve your problem. It might do what you need. It might be better than what you'd come up with. But do you always have the time to look into it? At the end of the day, is it more satisfying to spend your afternoon writing your cool new widget, or decyphering the docs for something that already exists? I feel like I've accomplished more when I write a library that works than when I've just spent my time learning how to use one. Libraries should be easy, not difficult.
Side note - I'm also assuming that there exists a gizmo to do what you want to do. Further, I'm disregarding the fact that you may write a superior one or come up with a novel approach or whatever. Both of those can come up in reality, but we're ignoring 'em for the moment.
Here's a personal pet peeve (which, again, I'm quite guilty of) - modules that have "documentation" that consists of little more than lists of method names. So you know how to create an object and can dig through a list of all of its attributes....And then what? How do you put it all together?
I want to see use cases. I want to see examples. I want to see lists of things that I can cut and paste into place to solve my common problems. I don't care about long, expository paragraphs. I don't care about lists of methods (yet). I just want something I can copy out, paste in, tweak a little, and use.
Libraries are supposed to save me time. So save me time!
Compare, and tell me which one looks easier to follow:
Kool::Widget is a Widget that does Kool things
Kool::Widget is a widget for doing kool things, such as frobnication, bazification, and fooination. Kool::Widget was born out of a desire to see more frobnification (as well as frobnication!) on the internet and because I didn't feel that the existing tools properly operated in this capacity.
It is an OO module that uses standard perl concepts and idioms to prevent your frobnification in an easy manner.
Alternatively, how about this:
Kool::Widget - a toolkit for frobnication, bazification, and fooination, by Me.
"But Jim," you protest, "This example doesn't make any sense! You made up methods and attributes and concepts! I don't follow!" My retort is you shouldn't need to follow. You've hunted down something for frobnification, so you already know the basic concepts, and I want you to concentrate on the concept presented instead of pointing out a bug in my XML parser.
"But Jim," you protest, "You just added a few more examples and reversed the order. This doesn't change anything!" I submit that it does:
"But Jim," you protest, "This is completely throwing out the established perl documentation standards! NAME! SYNOPSIS! DESCRIPTION!" And I reply that you're absolutely right. I think we can do better.
Another note - gimme tools! If I can download something and run a little contraption you've built to save me more time, that makes it that much easier for me. For example, take the plethora of OO systems that are out there - all of us should be providing tools to generate modules. You have a database abstraction layer? Give the user a tool to automatically generate a module that maps to his database table. It seems like everyone that I've spoken to that uses an ORM package writes a tool to do that anyway after they get sick of creating cookie cutter modules, so provide it! I can build my modules using your contraption, I can copy and paste your example, and then I can get my job done. I'm a happy camper.
So now what? Well, personally I'm going to try and update my documentation to look more like this as I update my libraries, modules, whatever. I'm not going to race out and just change the docs, but with the next update? Yeah, I'll do it then.
Everybody else? I dunno. Did I make any sense? Did it seem reasonable? Do you maintain any libraries or modules? Give it a try the next time you do an update. At a minimum, I will thank you for it.