Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re: Who's afraid of the manual?

by Fengor (Pilgrim)
on Jan 03, 2002 at 13:18 UTC ( #135943=note: print w/ replies, xml ) Need Help??


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"


Comment on Re: Who's afraid of the manual?

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (15)
As of 2014-10-24 16:12 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    For retirement, I am banking on:










    Results (132 votes), past polls