On Sun, Jul 11, 2010 at 2:53 PM, Chris Marshall <[email protected]> wrote: > Maybe a Tips and Suggestions section? Isn't there a section > on the wiki with cookbooks with PDL that would fall under the > same category?
But we don't have a lot of pages with tips & suggestions (I think we have two, including the wiki). I don't think they deserve another category. In the long run, what I want to have is a "User Guide" instead of "Tutorials". A user guide is more broad, and it can have a Philosophy section, and a Tips section. But I don't want to use the term User Guide right now because that term implies a certain amount of cohesion and consistency that the PDL docs simply do not have. So my goal for the future is to clean up the documentation and gradually turn the Tutorials section into a PDL user guide. > >>> * 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 would move it to the advanced section since it is definitely > important reading if you want to subclass from PDL. Keep the > "work in progress" note there. Ok. Done. >>> * 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. > > You had me at "No no no". :-) If it doesn't cost too much, > how about putting that link at the top of all the top level > doc pages. Tutorial users and Reference searchers can use > the reminder. That's very good idea. Done. > The comment was only for the minor heading rename. > We've already had a lot of discussion about module > structure. I was pointing out that from a user's > point of view, how to drive PDL is of much more > relevance than what the engine components are under > the hood (the perl modules of the implementation). Ok. I thought you were suggesting something more than just changing the page title. >> Would you move PDL::Core to the "Advanced" section and leave the user >> to learn about the "pdl" function from the tutorials? > > Again, this was about substituting Fundamentals for > Beginner and not about restructuring modules to make > the reference pages turn into optimal user level refs. Ah. I get it now. >> 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? > > I think you lose a lot by not having the functional > grouping. For example FFT and FFTW both calculate > the FFT. Splitting them up means someone may end > up using the slower internal routine even if they > have installed the FFTW version. I understand. I'm willing to go with the majority on this. What does everyone prefer? I guess we could put them all together and add some sort of warning about it requiring an external library, similar to what you suggested: > Fast Fourier Transform: > PDL::FFT > PDL::FFTW (optional) > PDL::Lib::GSL::FFT (optional) >>> * 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. > > Top level PDL projects page at sf.net: > http://sourceforge.net/projects/pdl/ > > Bugs tracker at sf.net: > http://sourceforge.net/tracker/?group_id=612&atid=100612 > > Feature request tracker at sf.net: > http://sourceforge.net/tracker/?group_id=612&atid=350612 > > PDL git page on sf.net: > http://sourceforge.net/scm/?type=git&group_id=612 > > Browse PDL git repository at sf.net: > http://pdl.git.sourceforge.net/ Ok. I'll add links later today. About the "Get Started" page: Give me some time to think about what you wrote. I see things differently from you, but rather than start an argument, I'll try to find something that we'll both find satisfactory. That said, some comments: * I think your Honda analogy makes no sense. We are not a dealership selling Git. We are "selling" PDL and Git is a tool we use. * Technically there is no need for us to write Git documentation either. Git already comes with manuals that are perfectly suitable. I wrote the documentation in part because I like writing documentation and I like being thorough. And yes, I do have a personal motivation to encourage non-Git users. I think very highly of Bazaar, Mercurial, Monotone and Darcs. They have much to offer and I want to invite users who prefer one of those SCMs. Please allow me to scratch a personal itch. That's part of what makes open source projects work well. As I said, I will make an effort to make a page that we'll both find satisfactory. 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
