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


in reply to Re: Please for the love of god, can I get a documentation format that doesn't suck?
in thread Please for the love of god, can I get a documentation format that doesn't suck?

Probably the only solution is to provide a good set of guidelines for the use of POD (or whatever markup may be used) so that both usage and apperance are consistent.
Yes...and no.

The OP was specifically working with perlvar.pod, and complained about the inconsistency of POD usage therein. If a single document is legitimately judged inconsistent, guidelines won't help.

However, it may be that the nature of perlvar.pod is such that POD is overly taxed (or POD writers are overly taxed commenting it).

I'm curious to see whether perlvar.pod is judged to be well formatted (POD-wise) or not, and whether the blame or kudos can be lain at the feet of an individual or an anonymous horde.

-QM
--
Quantum Mechanics: The dreams stuff is made of