http://www.perlmonks.org?node_id=614441


in reply to Re^2: Programming *is* much more than "just writing code".
in thread Programming *is* much more than "just writing code".

There's also the problem that purely textual changes, from typos to reattributions to rephrasing of prose can trigger RCS trails associated with the code that shouldn't be. Documentation also belongs in the RCS system, but as independant entities to the code, so that documentation changes do not affect the revision history of the code and vice versa.

This is actually a very good point (though I have to say I thought that I was the last person in the world using RCS for version control). Documentation and comment changes are more common than actual code changes (at least if you're someone like me who does re-write it to keep it up-to-date), and it might be better if those changes weren't cluttering the logs.

Damien Conway recommends against putting project documentation in a dedicated *.pod file: he argues that there's no way to be sure the *.pod will get installed correctly in some place where it can be found, but if it's inside the *.pm file, you know it's always going to be with the code.

In part, under the influence of Conway, I've been sticking to a documentation style where more tangential/higher-level material is confined to some pod at the bottom of the *.pm file (I'm a fan of "MOTIVATION" sections myself, they're often the key thing that makes clear whether you want to use a module at all). But in a multi-module project, I find I definitely have a problem with repeating myself too much, e.g. stating the project's purpose over-and-over again...

There are some clear advantages with having a project overview pod file elsewhere.