I agree fully that pod is insufficient for so many things that it is currently being used for. Thanks for raising the issue. My solution would have been different, but I think you've taken a step in the right direction. I hope the next generation of perldoc, has two discrete functions: the first to comment code, the second to provide tutorials, and howtos. I think the code-comments should be reserved largely for notes that help developers -- what is traditionally a "comment" in other language. The latter function should be something that is heavily dependent on community, internet access, and frozen state wiki concepts. Something kind of like a remote repository of texttile documents, that you can pull from, edit and push back to. With cpan being a web interface frontent to it. I'm still thinking about how this should be done, something with XMLRPC, and some VCS voodoo seems to be the way to go.