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;
}
[download]

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.

How do i create my own post here ? I dont find any way to do that.

The post you're replying to is six years old. Perhaps you should post your own question, clearly in SoPW.

With the above example, you could see if the $member->fileName matches one of the file names you are interested in.