Daniel, On Thu, Jul 8, 2010 at 1:11 PM, Daniel Carrera <[email protected]> wrote: > Hello all, > > Since I have some time this month, I have continued my quest to > improve PDL's website and documentation. I updated the website today, > you can go to http://pdl.perl.org and see the changes.
Very nice work. This is the "first face" of PDL for the rest of the world, so a very important task. Here are a few suggestions from my perspective as a user -- http://pdl.perl.org and http://pdl.sourceforge.net are the same sites, hence, in my view, should have the same URI. Making one or the other the canonical identifier would be very helpful. (I would prefer pdl.perl.org). > > I'm trying to take a methodical approach to fix the site. In "Round 1" > (last May) I focused on the look & feel of the website. I also changed > the backend to make it more flexible. Now, in "Round 2" I have focused > on the organizational structure of the website. > > The first thing you'll notice is that the sidebar has changed a fair > bit. Although it is much shorter now, it actually has roughly the same > information as before. It's just better laid out, with less > duplication and redundancy. To make everything work, I did have to do > some work on the content: I find it very difficult to figure out where to look for the docs for a command. So, I first go to perldl> and type 'help <command>'. However, I find it hard to read the docs in the terminal (the paging is sub-optimal), so I then go to the web site and look at the specific docs. A ubiquitous search field on the web site would be a fantastic help in the above, kinda like an analog of 'help command' at the perldl> prompt. If I am going whole-hog with my wishlist, an auto-suggest for the search field would be very cool, as well as a fuzzy search on the backend. In any case, most site search tools should be able to do the latter. The quickest way to implement a site search might be, however, to implement a Google custom search. It is a few lines of code, and just pops in the page. Then you just wait for Google to index the page, and you are all set. > > 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. > Another thing I find difficult is jumping from doc to doc, say, when looking at the docs for two different commands that are in two different modules. Since there is no ubiquitous document index (a table of contents) on every page, I have to browse back to the "reference docs" page and then find the other documentation link I want, and go to it. I figured that I could just change the URI in the address bar. So http://pdl.sourceforge.net/?docs=Core&title=PDL::Core The URI seems to have a possibly superfluous title=<title>. If I just change the docs=<doc name>, I go to the correct page, but sans the title. For example, http://pdl.sourceforge.net/?docs=Ops takes me to the Ops documentation, but now the title is missing. Of course, I could add the title, but that can lead to interesting possibilities as by http://pdl.sourceforge.net/?docs=PDL&title=Scipy .. > > 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. > This is great work and service done by you. Much appreciation to you for that. I will soon send you the code and instructions for the PDL users map that may be put up on the web site. Many thanks, Puneet. _______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
