Na ja, wenn man sich CPAN anschau, sieht man, das das alles in POD Dokumentiert ist. Und in HTML geschrieben. Und die Dokumentationen sind durchaus sehr einfach und gut verständlich... Die Dokumentationn sind nur so gut, wie sie der Autor geschrieben hat. Ich finde das hat generell mal nichts mit Perl zu tun. Mal ehrlich, wenn du ein script schreibst, sagen wir mal so knapp 500 Zeilen, machst du dir doch sicher auch über andere Dinge einen kopf, wie:

Wie kann ich das am besten dokumentieren, damit auch jeder, das versteht und am besten auch, ohne meine Sprache sprechen zu müssen...

Für jemand, der sowieso schon so viel auf die Beine gestellt hat, wie eine Doku über alle Spezialvariable etc zu schreiben, muss man schon sagen, dass es doch gut verständlich ist!
Wenn man sich überlegt, das die Doku`s auf jeden Fall schon auf dem Rechner sind und man die "offline" durchgrepen kann, find ich, ham die Autoren durchaus Respekt verdient..