To make the module more friendly to beginners, the documentation might offer examples of potentially tricky situations (for beginners)...
- examples of how to use checkboxes & radio buttons
- examples of how to use use pull down single-select menus
- examples of how to use multiple-select menus
- examples of https and https-with-post
- examples of using WWW::Mechanize::Shell to speed things up
- examples of wise WWW::Mechanize use (check return codes on every page, check page returned is the page expected, etc)
- tips for WWW::Mechanize debugging
As I said in OP, I am a big fan of W::M and W::M::S. They are great modules. However, better docs could allow more folks to benefit from their power and convenience.