Beefy Boxes and Bandwidth Generously Provided by pair Networks
go ahead... be a heretic
 
PerlMonks  

Re^7: Put some of the posting guidelines directly above the posting form:

by ww (Archbishop)
on Dec 04, 2011 at 22:10 UTC ( [id://941768]=note: print w/replies, xml ) Need Help??


in reply to Re^6: Put some of the posting guidelines directly above the posting form:
in thread Put some of the posting guidelines directly above the posting form:

"I think that it is all too easy for those with long-term familiarity with the Perl docs to assume they are the very model of suffice and clarity, forgetting the struggles they themselves once had with them."
      :-{)

Trust me! That's not me you're talking about, whether because of my own (relative) nooby-ness, my lack of a formal cs background; or simple simple-mindedness... but for my $.02, far too many perldocs -- esp. those for modules -- are on a par with the worst of the nixish documentation -- reflecting, IMO, a mindset by the writers that "I know what I mean; I worked hard to get here; let the reader share the pain."

Want a specific example of a core doc which doesn't begin to say enough to make use of its function? read truncate (which, unlike the POSIX doc for truncate(), fails to mention writability as a precondition); want one that's merely confusing or ambiguous? There's a wealth of such docs.

Fixed link to the truncate doc

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others goofing around in the Monastery: (7)
As of 2024-03-29 11:39 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found