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 / com
www.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 online api docs? 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