[Proto-Scripty] Re: New API Doc
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
[Proto-Scripty] Re: New API Doc
TJ- First, it's great to see there's diligent activity on the docs, which seemed like they went stale for a while there. To the whole team, keep up the great work! Definitely need the quick-look menu of methods (and any other properties) provided by each of the major classes. i have a suggestion for enhancement, and two issues with the new docs: Enhancement: It might be helpful to somehow indicate from the (to-be-improved) navigation when a method HAS, or IS, an alias. Why do i want to see the actual documentation on Enumerable#select or Enumerable#filter when all it's going to tell me is Alias of Enumerable#findAll? Especially when they don't operate any differently. Show me that in the menu so i can just go to #findAll directly. Or better yet, don't give aliases a method-level entry at all. Perhaps something like the following: * Enumerable - link to main Enumerable doc - findAll - link to #findAll, where the aliases are also noted (filter) - link to #filter, if the user REALLY wants to see it (select) - link to #select, if the user REALLY wants to see it Issues: 1. This seems isolated to Firefox/Gecko. The menu panel doesn't scroll normally. i have no idea why, but it scrolls about 1/10th the expected speed, which is a nuisance. 2. This one is happening in all browsers. If i click Element (for instance), location bar says http://api.prototypejs.org/dom/element.html If i then click #select, i'm taken to that method: http://api.prototypejs.org/dom/element.html#select-class_method Great. But the natural impulse (mine, at least) to get back to that list of methods is to use the browser's Back action. Gotcha! The location bar returns back, but the browser window doesn't. Thanks! -joe t. On Oct 27, 7: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
[Proto-Scripty] Re: New API Doc
Hi Joe, I think you've gotten the wrong impression -- I'm not in charge (or control) of the new doc stuff, that's Tobie Andrew with some help from a couple of other people. All I've done is try to merge in (and update) the old API docs content into the new stuff, since it hadn't been done. But I know Tobie Andrew are very open to suggestions and eager to improve the new docs. My suggestion would be to log any issues you run into (or suggestions) on Prototype's Lighthouse project[1], flagging them appropriately as either bugs or enhancements. Some of them may or may not be more appropriately filed on the PDoc project[2] instead, but it's a bit hard sometimes to tell where a problem is, so I'd tend to lean toward reporting them on the Prototype project. [1] https://prototype.lighthouseapp.com/projects/8886-prototype/overview [2] https://prototype.lighthouseapp.com/projects/8889-pdoc/ HTH, -- T.J. :-) On Oct 29, 1:23 pm, joe t. thooke...@gmail.com wrote: TJ- First, it's great to see there's diligent activity on the docs, which seemed like they went stale for a while there. To the whole team, keep up the great work! Definitely need the quick-look menu of methods (and any other properties) provided by each of the major classes. i have a suggestion for enhancement, and two issues with the new docs: Enhancement: It might be helpful to somehow indicate from the (to-be-improved) navigation when a method HAS, or IS, an alias. Why do i want to see the actual documentation on Enumerable#select or Enumerable#filter when all it's going to tell me is Alias of Enumerable#findAll? Especially when they don't operate any differently. Show me that in the menu so i can just go to #findAll directly. Or better yet, don't give aliases a method-level entry at all. Perhaps something like the following: * Enumerable - link to main Enumerable doc - findAll - link to #findAll, where the aliases are also noted (filter) - link to #filter, if the user REALLY wants to see it (select) - link to #select, if the user REALLY wants to see it Issues: 1. This seems isolated to Firefox/Gecko. The menu panel doesn't scroll normally. i have no idea why, but it scrolls about 1/10th the expected speed, which is a nuisance. 2. This one is happening in all browsers. If i click Element (for instance), location bar sayshttp://api.prototypejs.org/dom/element.html If i then click #select, i'm taken to that method:http://api.prototypejs.org/dom/element.html#select-class_method Great. But the natural impulse (mine, at least) to get back to that list of methods is to use the browser's Back action. Gotcha! The location bar returns back, but the browser window doesn't. Thanks! -joe t. On Oct 27, 7: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
[Proto-Scripty] Re: New API Doc
Forgot to say: Great. But the natural impulse (mine, at least) to get back to that list of methods is to use the browser's Back action. Gotcha! The location bar returns back, but the browser window doesn't. I *thought* I'd seen that the other day and was irritated by it, glad to know it's not just me. I was in too much of a rush to go into detail at the time. -- T.J. :-) On Oct 29, 1:23 pm, joe t. thooke...@gmail.com wrote: TJ- First, it's great to see there's diligent activity on the docs, which seemed like they went stale for a while there. To the whole team, keep up the great work! Definitely need the quick-look menu of methods (and any other properties) provided by each of the major classes. i have a suggestion for enhancement, and two issues with the new docs: Enhancement: It might be helpful to somehow indicate from the (to-be-improved) navigation when a method HAS, or IS, an alias. Why do i want to see the actual documentation on Enumerable#select or Enumerable#filter when all it's going to tell me is Alias of Enumerable#findAll? Especially when they don't operate any differently. Show me that in the menu so i can just go to #findAll directly. Or better yet, don't give aliases a method-level entry at all. Perhaps something like the following: * Enumerable - link to main Enumerable doc - findAll - link to #findAll, where the aliases are also noted (filter) - link to #filter, if the user REALLY wants to see it (select) - link to #select, if the user REALLY wants to see it Issues: 1. This seems isolated to Firefox/Gecko. The menu panel doesn't scroll normally. i have no idea why, but it scrolls about 1/10th the expected speed, which is a nuisance. 2. This one is happening in all browsers. If i click Element (for instance), location bar sayshttp://api.prototypejs.org/dom/element.html If i then click #select, i'm taken to that method:http://api.prototypejs.org/dom/element.html#select-class_method Great. But the natural impulse (mine, at least) to get back to that list of methods is to use the browser's Back action. Gotcha! The location bar returns back, but the browser window doesn't. Thanks! -joe t. On Oct 27, 7: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)
[Proto-Scripty] Re: New API Doc
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 in http://php.net/function_name_here -- concrete example being stripos (is it haystack first, or needle first? I never can remember) http://php.net/stripos and 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
[Proto-Scripty] Re: New API Doc
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-- A big +1 for that, I really like that about the old docs. -- T.J. On Oct 27, 11: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
[Proto-Scripty] Re: New API Doc
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
[Proto-Scripty] Re: New API Doc
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 -~--~~~~--~~--~--~---
[Proto-Scripty] Re: New API Doc
I agree with you as it seems less documented (read: less examples seem to be provided). I'm sure though that since it's only a relatively new release of the documentation system, more information and examples will probably be added soon. Either way - we should all be thankful to anyone investing their time into this project :) On Oct 8, 7:21 pm, 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 -~--~~~~--~~--~--~---
[Proto-Scripty] Re: New API Doc
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 -~--~~~~--~~--~--~---
