Oh, I understand the reasons and even agree in principle—that current docs are more important than some concerns and having them in your face is a reminder to keep them current. And I'd much rather see POD somewhere than no POD. And a code/POD dumper is an interesting idea. So many "and"s. Still I don't think—for most people, I don't hard prescribe or proscribe, only try to find best practices—it prevents more trouble than it causes. If there is no inline POD, I can have 2 or maybe even 10 or 15 subs in the terminal at once. When I'm debugging or trying to think straight, that is much more valuable for cognitive load; yes, I suppose some IDEs can hide/show POD/comments and I don't doubt LanX will have an emacs macro for perl-mode.tt to do it after reading this :P but still. And sometimes you're stuck on a remote terminal you have no control over or on an IDE you don't know. Additionally—so many "and"s are horrible style but don't let my bad style get in the way of my preaching about style, uhmmmm…—many, probably the lion's share of devs won't update or write the POD regardless of where it is. Like the car manual analogy, consider the footnote; publishers having centuries of accumulated practices in presenting written information. Inline footnotes would be awful. Even the bottom of the same page is slightly controversial with some publishers opting to put them at the end of the complete text; I find this similar to POD after the __END__ (as the bottom of multiple pages/modules) or in a completely new .pod file; external to the code/text.

An advantage of completely separate code and docs is you can trivially ship or build without docs if you want. Of course with PPI and such you can strip it no matter where it is. So… viva Perl.