Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

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

by GrandFather (Cardinal)
on Sep 10, 2005 at 23:42 UTC ( #490951=note: print w/ replies, xml ) Need Help??


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

Yet another manafestation of TIMTOWTDI. The fault isn't with POD, which is just a form of mark up, but with inconsistency with its use. You can't avoid people using the richness that is provided in ways you didn't anticipate; that's what people do.

Changing from one type of markup to another doesn't solve the fundamental problem, and in the case of POD to XML, probably makes it worse!

Remember the context for POD. It is to help provide documentation in the source, so any markup that is used to manage formatting in some other context has to be pretty light weight or the documentation just doesn't fit with being in the source in the first place.

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.


Perl is Huffman encoded by design.


Comment on Re: Please for the love of god, can I get a documentation format that doesn't suck?
Re^2: Please for the love of god, can I get a documentation format that doesn't suck?
by QM (Vicar) on Sep 11, 2005 at 01:40 UTC
    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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://490951]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others rifling through the Monastery: (6)
As of 2014-09-16 01:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite cookbook is:










    Results (155 votes), past polls