I recognize how hard documentation is to write, and I'm grateful that PDL has so much of it. However, there is room for improvement. The following comments are intended as an objective critique and to start a discussion which can lead to cohesive design and documentation standards.
The current documentation is a combination of user guide, history lesson, notes to self and reference manual. There are a few things we can learn from other successful projects that would improve it. 1. Separate out the different approaches into different document hierarchies. (Type::Tiny[1] and the Template Toolkt[2] have done that pretty well) I think the documentation falls naturally into these categories: a. Reference manual: terse, complete documentation accompanying every method and subroutine. The documentation should reflect which version of PDL a method was added or when its behavior changed. Documentation should reflect the current behavior, not changes from previous behavior. That adds confusion and never gets removed even when the change happened years prior. Knowing when behavior changed allows the user to find the older docs and compare. b. User's Guide. This would be topic focused and live in the PDL::Manual hierarchy c. Tutorials: These would include beginning to end discussions of how to do a more complex analysis and would live in the PDL::Tutorial hierarchy d.. Cookbooks: How to solve specific problems using PDL wizardry that might not be obvious. These would live in the PDL::Cookbook heirarchy. 2. Have a single source for the documentation. Currently there's pdl.perl.org and metacpan. That's one too many. For ease of maintenance we should choose metacpan and sunset the documentation on pdl.perl.org. We don't have the resources to handle both. 3. Math, table, and graphics support This is a difficult area, as POD is a very primitive format. I'm not sure how far we can push things. There are ways of marking sections to provide different input to different renderers, but that makes it difficult for documentation authors. We will need tools to generate POD which contains output for those without the special renderers. We would also need to work with Metacpan to see if they are open to rendering math and tables using optional renderers. For mathematical notation, we would need to standardize on a single format. One option is to write it in asciimath[4] (I personally can't read LaTex math very well, even though I've used it for eons. I use LyX to write anything with an equation in it.). If we need to ditch POD and move to another format, than Sphinx[5] (used by readthedocs[3]) produces very nice technical docs. (GSL has moved to it and it has really improved their documentation[6].) That would require generation of HTML for the static documentation on metacpan and I don't know how well that would work. The nuclear option would be to move the documentation to readthedocs[3] or some other similar site. To be clear, this is not at all what I'd like to see happen, but it would provide us with nice docs out of the box. [1] https://metacpan.org/release/Type-Tiny [2] https://metacpan.org/pod/Template [3] https://readthedocs.org/ [4] http://asciimath.org/ [5] http://www.sphinx-doc.org/en/master/ [6] https://www.gnu.org/software/gsl/doc/html/index.html _______________________________________________ pdl-devel mailing list pdl-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/pdl-devel
