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/striposand I'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