I agree with you on the docs. I am not quite sure what to do about it though.

I think a first step would be to enhance the tutorial, by adding more examples and sections on more advanced topics. Maybe I should include it with the module too.

Then... I don't know. Maybe check that the quickref card is complete and up to date.

In any case there needs to be a reference, that documents each method. That's the current module doc. I would gladly accept any idea to improve it's layout, organisation... really anything about it.

In a previous thread Tanktalus suggested breaking the documentation up more so that the element documentation doesn't collide with the twig documentation and so on. The reply mentioned the tension between searching multiple places for information and being overwelmed by a huge document with the author's inclination falling on the side of one large searchable document.

I understand that viewpoint, however I'd be inclined to split the document up and add an overview document with links to the main documentation for each part. A number of improvements can then be made:

• fuller description of individual functions
• more example material can be added
• preferred function names should provide full documentation for the function
• function documentation provides a full list of aliases
• function aliases simply link to the section for the preferred name
• the overview document lists all members and provides links but no further function documentation
• a fully worked examples document that uses current examples plus answers provided to common SoPW questions (links to the questions would be really cool)

Having the documentation available offline is important for those times you are working offline and need some help. A web based tutorial is fine, but is not a substitute for good POD documentation.

I'm available to help refactor and proof edit the XML::Twig documentation if required.

---

DWIM is Perl's answer to Gödel

Perhaps the first thing in the perldoc should be "This is just a reference - if you want full docs, please see.."

Oh, that's what you already have. :-)

Seriously, the only change I'd make is to create a new section at the top, ABOVE the synopsis, to draw attention to the text. Something like:

=head1 FOR NEW USERS

This documentation is intended as a reference.
If you want to learn how to use XML::Twig in a
 friendly manner, please see http://www.xmltwig.com/xmltwig
[download]

Depending on your humour level and style, the next lines could be:

=head1 HERE BE DRAGONS

Don't read the rest until you've come to understand XML::Twig
from its website.
[download]

But maybe that's just my sense of humour there. :-)

I just started using XML::Twig for the first time within the past few weeks for a $work project. I've found a somewhat steep learning curve, as compared to other modules I've started using very quickly. But it's a great module, and I'm so glad I don't have to be stuck writing XSLT--yuck. It's been useful to have a single documentation source with everything in it.

But you all are correct that newbies could get started much faster with some other docs to begin with.
What allowed me to start getting work done was the help page with links to some selected XML::Twig conversations here on Perlmonks. Finding examples that were similar to what I wanted to do with XML got me started the fastest.

Many of the more complex modules also have additional Cookbook-style pod. Like Parse::RecDescent, Catalyst, and POE for example.
Perhaps XML::Twig documentation could benefit from a "Cookbook" style doc that gives maybe a dozen of the most common tasks that XML::Twig would come in handy for, or general tasks that can serve as building blocks to piece together into more advanced usage.