Let's see what I can do:

I suppose I would put the XML::Twig::Elt docs into XML::Twig::Elt

See, I hate that. I have answered countless questions about XML::Parser with just a link to the docs for XML::Parser::Expat, because a lot of people don't realize that part of the doc is there. And I hate navigating the docs for basically all DOM modules, because the method I want to read about is always in an other class, hence in an other file. But I have an HTML version of the docs where you can expand/collapse levels, at http://xmltwig.com/xmltwig/twig_dev.html . It has some quirks, but it is what I use normally.

Maybe even an XML/Twig/Tutorial.pod would be nice

There is a tutorial at http://xmltwig.com/xmltwig/tutorial/index.html . It wasn't written in POD but rather in XML, with all the source code in separate files, so it might be difficult for me to create a POD from it (is there an HTM2POD converter somewhere?)

I found many ways to set the tag (gi, set_gi, tag, set_tag, ... did I miss any?)

Actually set_gi and set_tag are the only 2 ways, the other ones just return the tag. I apologize for this one. I am an SGML guy and tags were called gi's back in the days, but after being mocked for years by the young XML crowd I finally broke down and added tag and set_tag as aliases for gi and set_gi respectively. So yes, guilty here, but most of my code uses the gi form, so I am kinda reluctant to deprecate it ;--(

You have a lot of options which duplicate each other. This simply helps obscure the unique options

Agreed. There (of course!) reasons for a lot of those:

• methods like tag/gi as already mentioned, where the domain vocabulary has changed in the lifetime of the module,
• methods that are internally the same but represent different things for the users: first_child_text and field are synonyms, as are has_atts and att_nb, but I thought it made sense to express them differently,
• methods that have a "Twig style" name but that also exist in the DOM or in HTML::Tree, like descendants and getElementsByTagName, and I agree this is probably overkill. Or at least I could document them separately,
• finally, and once again I guess I have to take the blame, some aliases are quite whimsical, like sort_children_by_value and sort_children_on_value, which are both available because I couldn't decide which one I prefered

In the end I guess all those aliases are a somewhat conscious design decision, to include everything and the kitchen sink in XML::Twig, to the point of indeed overwhelming users whith too many methods. It was also part of my master plan for for generating lucrative training gigs (no success there so far ;--(

I also found (maybe this is just me) that paste was counterintuitive.

You are not first one to think like this. I even added the, rather cryptic now that I read it again, The element is pasted sentence to the docs to warn users about it. I have now added a longer explanation. Note also that the method explecitely checks (and croaks) if the arguments appear to be reversed.

Thank you for your comments. As mentioned I slightly tweaked the docs, and I moved the paragraph about additional resources to the very top of the POD, so hopefully users will have an easier time going through the learning curve. I think that's the best I can do right now. I have known that I will have to rethink the docs and try to come up with more material for the tutorial for quite a while, but I keep finding new things to code instead!