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

deprecated has asked for the wisdom of the Perl Monks concerning the following question:

I'm starting a project that will involve seven of my coworkers, roughly a hundred separate files, and on the order of 45,000 lines of code. So I'm setting up a hierarchy that should remain somewhat sensible throughout the project. We're not worried about feature creep right now, we're in early prototyping.

So, OpenBSD has this great hier(7) manpage:

NAME hier - layout of filesystems DESCRIPTION A sketch of the filesystem hierarchy.
and suchlike. I'd like to be able to have a user just do perldoc hier and have it DTRT. However, it seems to me that I'd have to have a file named hier in there to be spat out. I was thinking of having a Pod/ directory, but that strikes me as somewhat of a hack, given there will be pod inline with the documentation itself.

I'd do it in pod and use pod2man and leave the documentation up to man(1), but doing that means that I'd need a makefile, and users wouldn't be able to read the documentation from within the source tree, they'd have to check it out, build it, then read it, and be careful not to commit the "built" manpages.

There's going to be a LOT of POD with this project, so I need some way to make the documentation intuitive for the user and developer.

How should I go about doing this?

dep.

--
Laziness, Impatience, Hubris, and Generosity.