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.

I would agree with this statement. The documentation reminds me of another module that is of great use but horrid documentation SOAP::Lite. There is a lot of documentation and unless you are very familiar with XML it is easy to get confused about how XML::Twig converts a document into code and vice-versa. I tried Dumping the object, and that told me nothing, it is kinda scary how much data you keep track of.

If you would like some help with the documentation mirod I would be willing to help as well.

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]

=head1 HERE BE DRAGONS

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