On 7/8/2010 2:11 PM, Daniel Carrera wrote: > > 1) I replaced the Documentation page by two pages: > Tutorials and Reference. Each of these is a > well-organized table of contents. They will go a long > way in making documentation easy to find for new uses.
This division helps to clear things up. > 2) I rewrote the Development "Get Started" page. It has > all the information from before, and I added > information about Git and Mercurial. This allowed me > to remove the two Git links from the sidebar. All the > information from those links (and more) is in the "Get > Started" page, and it is better organized. Good. > I would appreciate some help reviewing this site. Please > let me know if you notice any errors or can suggest > improvements. In particular, there are several modules > in the Reference section that I did not know how to > categorize. If you go to "Reference" and scroll down to > the bottom you'll see them. I would be grateful for any > help in assigning these modules to a sensible category. Here are my thoughts in a review of the new page, sort of in order but don't hold me to it... * Now that the web page has standardized to pdl.perl.org, refs in the FAQ and doc need to be updated * I think the first tutorials category might be better as Foundation rather than Beginner. * As far as I can tell, Dataflow, as described in the PDL::Dataflow page is not enabled in current PDL and doesn't actually work. The bidirectional data flow does work but it is covered in Indexing. * Tips and Suggestions: not really a tutorial * Object Orientation: not a tutorial and definitely not complete. Are we keeping a list of things needing updates? * I suggest a bit more detail in "How do I search for a function?" and move it to the tutorials page. Add a reference to pdl2 which is available in CPAN developers release and will be in the next official release of PDL. Also, add the ? and ?? aliases to the examples in the perldl or pdl2 shell. * The items in PDL Reference Documentation might better be termed PDL Modules Reference Documentation. From a user point of view, I think the references should be around features for using PDL to calculate and solve problems and not the breakdown of the Perl modules for implementation. * I would add a Fundamental category in the reference docs as well. The Perldl or Perldl2 shell is key for new users. The PDL::Core is the lowest level piddle support---more like unix/linix kernel functions rather than "beginner"ones. * Per our earlier list discussion: the only relevant user interface information 3D graphics at the Beginner or Intermediate level is PDL::Graphics::TriD. The other TriD routines are for the implementation and, as mentioned, are still targets for refactoring for the new TriD support. * Breaking out External Library for the Numerical Methods and Images seems confusing to me. From a users point of view, the important thing is the functionality and that the module may or may not work unless PDL has been built to support it. * PDL::MatrixOps is the most primitive matrix ops module in PDL. PDL::Matrix just wraps things up so folks can use column major syntax. * Develop with Git definitely needs a link to the sf.net browse the git repository. * Would be much less confusing if the Develop with Git actually explained how to develop with git. Any explanation is delayed until Hg is thrown in the mix. I think Hg may be nicer than git in some respects but it is confusing to new developers to present them both as if they were on an equal footing. I recommend explaining git development and having a link to a Mercurial page for folks familiar with that. * Please put a direct reference to the PDL sf.net page and a link to Feature Requests tracker. Great work! A big improvement and much more approachable.... Sorry the feedback took so long. Cheers, Chris _______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
