The stupid question is the question not asked | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
Good advice, good feedback!
If you need to teach or preach move it to separate documents.This was that "separate document". :-) If that wasn't clear, well... I said 75% done. Maybe it is 60%? :-(
As I wrote in the document: Read the Introduction document before looking at this, so you understand what Tree::Model does. After this document, you should read the programming APIs and the examples. Start with the pod/documentation for top.pm and then sysOwner.pm.
And in the post, before the documentation: In addition to this, there is an Introduction (I put it here: BerntB's BerntB's scratchpad and pod files documenting the method calls. You might have to read the intro to understand this. And, yes, Tree::Model is a stupid name. :-) A better alternative would be appreciated? Basically - if I don't have a good idea of what a module does by the second paragraph of the description I usually stop reading. Very common, certainly! The intro at my scratch pad did that part. But people won't go there. I will rework this document so there is a short intro, then a reference to my real overview. You quoted Why/What -- I've heard argued that almost all documents should be written as newspaper articles. Most important things first, details next. I'll try to follow it. Update: On consideration, the standard pod layout you recommended do follow the "journalist structure with most important thing first. In reply to Re^2: RFC Is this readable?
by BerntB
|
|