Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
My opinion is that good documentation allows you to find what you are looking for quickly. So I'm all for content tables in lengthy doc's (make that alll lengthy docs not only perl doc's ;)

The bad thing about lengthy documentation is that it can be hard to read just because of the mass of information. A table of contents takes this whole mass of information and breaks it up in smaller more manageable parts.

The two advantages of this are:

  • It's easier to find what u are searching for (humans tend o remember chapter numbers better than line numbers ;)
  • The documentation will be more read. Since you can read small chapter when u have a little bit of time left and read a longer chapter when you have more time

just my 0.02 Euro
-fen

PS: just another crazy idea popped in mynd right now: Doc::Random - The fortune of Docs ;-)

--
"WHAT CAN THE HARVEST HOPE FOR IF NOT THE CARE OF THE REAPER MAN"
-- Terry Pratchett, "Reaper Man"


In reply to Re: Who's afraid of the manual? by Fengor
in thread Who's afraid of the manual? by Juerd

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (2)
As of 2021-10-23 11:19 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My first memorable Perl project was:







    Results (88 votes). Check out past polls.

    Notices?