If you need to teach or preach move it to separate documents.

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.