Furthermore, those who have written significant portions of the documentation have always shied away from copying sections into other relevant PODs. Which means there are a lot of cross-references. Unfortunally, there are even more cross-references missing. There is *no* index at all, unless you count the list of manual pages from 'man perl'. But that list is incomplete - it only lists the PODs from the /pod/ subdirectory, not the POD that comes with the core modules. Crossreferencing from the core PODs into the core module PODs is almost non-existing.
The documentation is overwhelming. At the same moment, it's often terse, and sometimes requires UNIX and/or C knowledge.
But it's easy to critisize. Many have done so. Not so many have actually tried to fix the situation. Noone has actually managed to write better documentation.
If I were to fix something, I'd first create an index, and the framework to keep the index up to date. BTW, I strongly disagree with the suggested directory structure in the piece you quote. Either you subdivide the documentation on topics, or you subdivide them on their presentation. But you don't put both subdivisions on the same level. Where would I go looking for a tutorial about internals? In the "Tutorials" directory, or in the "Internals" directory?
In reply to Re: Reorganizing or fixing Perl's documentation?
by Anonymous Monk
in thread Reorganizing or fixing Perl's documentation?
by BUU
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |