perlmeditation
jimt
<p>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.</p>
<p>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.</p>
<p>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.</p>
<readmore>
<p>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 <i>might</i> solve your problem. It <i>might</i> do what you need. It <i>might</i> 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.</p>
<p>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.</p>
<p>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?</p>
<p>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.</p>
<p>Libraries are supposed to save me time. So save me time!</p>
<p>Compare, and tell me which one looks easier to follow:</p>
<hr>
<h2>NAME</h2>
<p>Kool::Widget is a Widget that does Kool things</p>
<h2>AUTHOR</h2>
<p>Me</p>
<h2>SYNOPSIS</h2>
<code>
my $kool = Kool::Widget->new();
my $frobnicated = $kool->frobnoz;
</code>
<h2>DESCRIPTION</h2>
<p>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.</p>
<p>It is an OO module that uses standard perl concepts and idioms to prevent your frobnification in an easy manner.</p>
<h2>ATTRIBUTES</h2>
<ul>
<li>frob</li>
<li>bingo</li>
<li>boozle</li>
<li>horatio</li>
<li>gilpher</li>
<li>potash</li>
</ul>
<h2>METHODS</h2>
<ul>
<li>frobnoz</li>
<li>bazify</li>
<li>fooinate</li>
<li>petrify</li>
<li>set_current_time</li>
</ul>
<hr>
<p>Alternatively, how about this:</p>
<p><b>Kool::Widget</b> - a toolkit for frobnication, bazification, and fooination, by Me.</p>
<h2>EXAMPLES</h2>
<h3>To frobnicate</h3>
<code>
my $kool = Kool::Widget->new(
'weasels' => 77,
'pigeons' => 0,
'heartburn' => 'yes',
);
#get back an arrayref of hashrefs.
my $frobnicated = $kool->frobnoz(
'with_daylight_savings_time' => 0
);
#see what you've got
print Data::Dumper($frobnicated);
</code>
<h3>To bazify</h3>
<code>
my $kool = Kool::Widget->new(
'weasels' => 77,
'pigeons' => 0,
'heartburn' => 'yes',
);
#Prep the widget, throws an exception if it fails.
$kool->petrify('input_file' => '/path/to/file');
#returns a hashref
my $baz = $kool->bazify();
#see what you've got
print Data::Dumper($baz);
</code>
<h2>ATTRIBUTES</h2>
<ul>
<li>frob</li>
<li>bingo</li>
<li>boozle</li>
<li>horatio</li>
<li>gilpher</li>
<li>potash</li>
</ul>
<h2>METHODS</h2>
<ul>
<li>frobnoz</li>
<li>bazify</li>
<li>fooinate</li>
<li>petrify</li>
<li>set_current_time</li>
</ul>
<hr>
<p>"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.</p>
<p>"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:</p>
<ol>
<li><b>It changes the emphasis, both for the author and the user.</b> The first, most important part of documentation should be how to use it and get people going as fast as possible. It should be the first thing people see, and should be the first part of the docs you write. Don't bury a few examples at the end. Write them first. You're using your module, adapt the code you have that uses it to be your documentation!</li>
<li><b>Extra info is at the end, where it should be.</b> Most of your users probably aren't going to need every single feature in your module. They're not gonna hit every single method, or use every single attribute. They just want to do one or two things to do their jobs. So show 'em how, but let 'em look up the rest.</li>
<li><b>Methods and attributes can now be targeted.</b> In those examples up above there, your user probably won't know what the weasels and pigeons and heartburn flags are for. Or what the input_file going into petrify is. But they can see immediately from the example that they're important things, so they can head back to the docs and immediately look up what they are. No more sifting through a list of all methods or attributes trying to figure out what to do - now you just grep through it to the one or two items you know you need to care about.</li>
</ol>
<p>"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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</readmore>