in reply to Who's afraid of the manual?
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 Section
Meditations