I'll just pick one of the many examples I could think of as an example of what needs improving in Perl's documentation. Where do you look when you want to learn about hashes? When I added hash support to
VarStructor 1.0, I had to resort to a Perlmonks tutorial because I couldn't find the equivalent information in the perldoc.