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"
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
| |
For: |
|
Use: |
| & | | & |
| < | | < |
| > | | > |
| [ | | [ |
| ] | | ] |
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.