Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) 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:

sub unzip { my ($archive, $want, $dir) = shift; my $zip = Archive::Zip->new($dir.$archive); foreach my $file ($zip->members) { next unless ($file->fileName eq $want); $file->extractToFileNamed($dir.$want); } croak "There was a problem extracting $want from $archive" unless +(-e $dir.$want); return 1; }

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.


In reply to Re^2: Unzipping files using Archive::Zip by Anonymous Monk
in thread Unzipping files using Archive::Zip by Anonymous Monk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others cooling their heels in the Monastery: (3)
As of 2024-03-29 06:10 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found