> Big block of text that's probably useful, but I want a list of methods
> that's quick and easy, and always one of the first things I see.

Good point. JavaDoc has the same problem and it's bothered me for
years.  We want there to be robust class-level information; but the
index of methods should be readily accessible, not pushed down by the
class overview.

-- T.J.

On Oct 28, 6:15 pm, "Adm.Wiggin" <admwig...@gmail.com> wrote:
> A good example of "badness" in the new API is the page for the Array
> class.
>
> http://api.prototypejs.org/language/array.html
>
> Big block of text that's probably useful, but I want a list of methods
> that's quick and easy, and always one of the first things I see.
>
> On Oct 27, 5:29 pm, "Adm.Wiggin" <admwig...@gmail.com> wrote:
>
>
>
> > How's this going?  Very much interested in "Going back to page-per-
> > method (rather than a long run-on page)".
>
> > Having the side navigation easy to navigate in the page-per-method
> > style like the old documentation is also of paramount importance.  For
> > example, if I click on "Hash" in the sidebar, I should immediately see
> > an easy to read list of all the methods of the Hash class.  As it is,
> > they're in a big block, which is hard to scan through, where the
> > vertical (alphabetical) list was quick and relatively painless.  Lots
> > of times, I'm just looking to verify the order of parameters, and it
> > was very helpful to be able to find the exact method very quickly so
> > that in almost no time I'm looking at the page reading the order of
> > the methods.
>
> > Something else that might be handy way further down the road is an
> > easy way to access these pages by-url.
> > For example, if I need to look up a PHP function to very the argument
> > order, it's as easy as typing inhttp://php.net/function_name_here--
> > concrete example being stripos (is it haystack first, or needle
> > first?  I never can remember)http://php.net/striposandI'm there
> > immediately.  Obviously way down the road, but certainly something to
> > think about.
>
> > On Oct 9, 3:56 am, "T.J. Crowder" <t...@crowdersoftware.com> wrote:
>
> > > Hi,
>
> > > You're not the only one, not by a long chalk. :-)
>
> > > We're working on it.  Tobie, Samuel, and Andrew are working hard to
> > > improve the structure, navigation, and presentation, and I'm
> > > continuing the ongoing quest of copying over, updating, and fleshing-
> > > out the content (which is a manual and labor-intensive process).  You
> > > should see marked improvemenet in the online docs over the course of
> > > the next couple of weeks.
>
> > > What happened is that the project switched from having the
> > > documentation be a completely separate thing (in a difficult-to-use
> > > tool) to having the documentation be part of the source code (a'la
> > > Javadoc), using a new tool built for the purpose called PDoc.  That
> > > way, when someone changes or adds code, they can update the
> > > documentation at the same time, and hopefully the two will be kept
> > > much more in sync.  (The official policy, in fact, is that code
> > > patches with documentation impacts that don't include the
> > > documentation updates are rejected.)  It also simplifies the process
> > > of people reporting and offering patches for documentation errors/
> > > omissions.  However, the docs got inadequate testing (and weren't
> > > complete) when 1.6.1 was released.  1.6.1 *needed* to be released,
> > > there was a lot of good, urgently-needed stuff in there (generally,
> > > and for IE8 and Chrome).
>
> > > If you want to, you can still get to the old docs (for now) 
> > > here:http://prototypejs.org/api
>
> > > However, I expect to finish copying/updating/improving the content
> > > Real Soon Now (happen to be working on that today), which will at
> > > least address the content issue.  And Tobie and Samuel just had a week-
> > > long codefest on the tool so we should see those improvements very
> > > soon.
>
> > > One thing that would be *really* useful would be to know what it is
> > > you find difficult about navigation (and just generally what's
> > > difficult about using the docs), so that that feedback can, um, feed
> > > into the improvement process.  Two things that Tobie et. al. are
> > > already doing are
>
> > > 1) Going back to page-per-method (rather than a long run-on page), and
> > > 2) Adding syntax highlighting to examples
>
> > > I'm sure there are other things they're doing as well, those just
> > > happen to be the two I know of.
>
> > > What else needs to be done?
>
> > > Thanks,
> > > --
> > > T.J. Crowder
> > > Independent Software Consultant
> > > tj / crowder software / comwww.crowdersoftware.com
>
> > > On Oct 8, 7:00 pm, louis w <louiswa...@gmail.com> wrote:
>
> > > > It's also just plain hard to navigate and understand all of the
> > > > different methods available.
>
> > > > An example. If I select Event there is no longer the list of available
> > > > methods appearing in the sidebar menu. Then I need to scroll down a
> > > > page which is visually hard to scan to be able to pick out
> > > > 'isRightClick' in light grey text buried in a sea of bright blue
> > > > boxes.
>
> > > > Usability should be a key factor when redesigning a documentation
> > > > system. The amount of times a developer will be using this site is
> > > > high. They should be able to pop in, find what they want quickly and
> > > > leave. Not get lost poking around the site.
>
> > > > I sure hope this is all to do with it's infancy.
>
> > > > On Oct 8, 1:26 pm, DJ Mangus <d.man...@gmail.com> wrote:
>
> > > > > No. You aren't.
>
> > > > > Sent from my phone so pardon the spelling errors.
>
> > > > > On Oct 8, 2009, at 10:22 AM, louis w <louiswa...@gmail.com> wrote:
>
> > > > > > Am I the only one that missed the old onlineapidocs? This new one
> > > > > > seems hard to use.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups 
"Prototype & script.aculo.us" group.
To post to this group, send email to prototype-scriptaculous@googlegroups.com
To unsubscribe from this group, send email to 
prototype-scriptaculous+unsubscr...@googlegroups.com
For more options, visit this group at 
http://groups.google.com/group/prototype-scriptaculous?hl=en
-~----------~----~----~----~------~----~------~--~---

Reply via email to