> 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 email@example.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 -~----------~----~----~----~------~----~------~--~---