|Think about Loose Coupling|
Re^2: Unzipping files using Archive::Zipby Anonymous Monk
|on Mar 18, 2005 at 16:23 UTC||Need Help??|
Thank you for your post. It was very helpful. I'd like to reply to your question since the original poster did not. It is a couple of years later, but I think the situation is the same.
Speaking for myself, I would say that the documentation is difficult because I did not find out how to do what I wanted within 1 minute, without reading any documentation.
Let me explain: when I have a simple, standard problem, I begin by looking at the SYNOPSIS. If I don't find a match to my problem there, I start scanning the document, looking further on any interesting method names. I rarely read documentation from the start to the finish, unless I'm trying to do something obscure and I'm not sure how to go about it.
In this case, I received a single zipped file from someone and I wanted to unzip it. After 15 minutes of looking through the documentation, I still didn't have my answer, so I came here, did a search, and found a solution. My resulting code is probably not as elegant as it could be, but it is functional:
So your solution here was clear and instantly solved my problem, whereas the documentation wasn't and didn't.
My suggestion for improving the documentation would be to keep in mind that people are lazy and use cookbook style examples, like the one you gave here.
If your synopsis consisted of two examples, one for creating an archive and one for extracting one (like the above example, but with error handling*), you'd probably address 90% of what people want to do with the module. For the curious, or for those whose problems are complicated, there's the whole wealth of your detailed documentation.
You might also add some whitespace between examples in the synopsis and label them, for instance '# Unzip an archive' or '# Zip a directory'.
* I find the error handling a bit unusual, with its comparisions instead of the more usual my $foo = dosomething() or croak "Couldn't dosomething: ".$Package::Errstr; or my $foo = $do->something() or croak "Couldn't something: ".$do->errstr();. This is why in my example I opted to do my own error checking, which is clearly inferior as it won't tell me why the operation failed.