The PBP likes documentation in POD, in your source files, but wants it all in one chunk, separated from the code it documents. This is one of the suggestions in the PBP I not only disagree with, I find damaging. I feel strongly that the documentation goes as close to the code as possible, to minimize the distance between them and make the tendency to avoid updating them harder to forget.
The book warns this leads to contorted code or documentation. I have not seen that happen. What I have seen is having to re-arrange code so the documentation made sense. But if the documentation makes sense, the code seems to always make sense in the same order.
The book also says that keeping documentation apart from the code makes it easier to remember to update. It’s a separate step and you have to do deliberately do it, rather than just looking over the thing that’s there. As far as I have seen, that’s claptrap. If it’s not near the code, it doesn’t get updated, and then it’s wronger than it was before.
Everything I have done shows that documentation kept further from the code is harder to maintain – both in the cognitive load of needing to remember to do it, and in the technical aspect of not being able to see as much of the code and documentation as possible together – and less accurate.
I have found this to be a really bad suggestion, and one of the few in the PBP that I find not just wrong but damaging.