Hi Chris, I'm glad you like the changes over-all. Replies below:
On Sun, Jul 11, 2010 at 1:39 AM, Chris Marshall <[email protected]> wrote: > 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 Yes. The FAQ needs at least a quick review. For example, the Q's about Git and CVS should be replaced with a generic Q that points to the "Get Started" page. The Get Started page has everything the FAQ has about Git and much more. > * I think the first tutorials category might be better > as Foundation rather than Beginner. Sure. For consistency, I would use the same title in the References section. > * 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. Ok. > * Tips and Suggestions: not really a tutorial Yeah. And neither is Philosophy. But they are not references either. They fit better under Tutorial than Reference. > * Object Orientation: not a tutorial and definitely not > complete. Are we keeping a list of things needing updates? A lot of modules need updates. I haven't kept track. Should I just remove it entirely? I think I'll remove it entirely. > * I suggest a bit more detail in "How do I search for a function?" > and move it to the tutorials page. No no no. Let me explain. Imagine you are just learning PDL. When you go to the "Reference" page, you are not planning to look up a module. You don't even *know* the modules. You are most likely planning to look up a function. When you see "Reference" you are probably expecting a *function* reference. The beginner user is coming to this page thinking "I bet PDL has a cosine function, I want to look it up". But the Reference page will not give him what he wants. He'll see a bunch of modules and will frustratingly start clicking on modules... PDL::Basic, PDL::Primitive, PDL::Func (hey, cosine is a useful function, right?), and so on. Often he has to read the whole module doc before figuring out that this is not what they want. I am giving these users a way out. When a user goes to this page expecting a function reference, the first link they'll see explains how to get what they were really looking for when they came in. > * 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. The page *IS* divided around features: Graphics, IO, Image Processing, Numerical Methods, etc. What more do you want? What more *can* I do? Please remember that what we had before was an *ALPHABETICAL* listing of all Perl modules!! I have gone through this list and separated (1) pages that are not modules at all (2) pages that are so incomplete or low-level that they shouldn't be listed, (3) pages that are "foundation" or "advanced". Of the remaining pages, I spent days dividing them into meaningful categories. > * 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. A fundamental problem is that the PDL docs themselves are *not* organized with a view to what users need. The first function users need to learn is "pdl" and that is in PDL::Core, but the rest of PDL::Core is "advanced". Would you move PDL::Core to the "Advanced" section and leave the user to learn about the "pdl" function from the tutorials? > * 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. Ok. I'll remove them. > * 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. Ok. But the ones that use an external library might require an additional installation step. No? What would you do about that? Imagine how frustrating it would be if you couldn't predict which modules will work reliably and which ones will work in some computers and not others depending on what other libraries they have installed. How would you solve this problem? > * PDL::MatrixOps is the most primitive matrix ops module > in PDL. PDL::Matrix just wraps things up so folks can > use column major syntax. Ok. How do you think I should organize them? In the documentation I mention PDL::Matrix first. > * Develop with Git definitely needs a link to the sf.net > browse the git repository. What's the URL? The FAQ doesn't say anything. > * 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 don't see what's wrong with Hg. You can use Hg to develop with PDL and it is perfectly transparent. I was actually thinking about adding Bazaar too (but bzr-git doesn't do "push"). It's like if a project uses Subversion and they welcome Git users and points them to git-svn. I don't see your point of "equal footing", if it works then it works. You don't raise an issue with my choice of operating system or text editor because this is all transparent for you. Anyway, I did try several ways of writing this page. Initially I had Git and Hg completely separate, but I wasn't impressed with the results. I tested several of my rewrites on my wife, who is definitely a new user, and the version she found easiest to read is the one currently on the website. She did not think it was confusing at all, she thought it was the clearest version. Lastly, I wouldn't want to just remove Hg entirely. I would rather welcome all users, even those who do not prefer Git, and I would emphasize that you can use whatever makes you happy as long as it works and integrates with the project seamlessly. > * Please put a direct reference to the PDL sf.net page and > a link to Feature Requests tracker. By the sf.net page, do you mean pdl.sourceforge.net? Why? That's just a redirect now. Can you give me a link to the Feature Requests tracker? How is it different from the bug tracker I already link to? Daniel. -- No trees were killed in the generation of this message. A large number of electrons were, however, severely inconvenienced. _______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
