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. :-)