I agree with both Richard and Sander - and there might be a middle ground I think that community comments, examples etc are a good addition to documentation and help users that are starting out - it would also give the new user a sense there was someplace to go for help. There has been many times I was working with a new function and was able to figure it out from the community comments instead of the "official" documentation (no offense intended)
On the other hand full blown PHP documentation like is overkill and is too much too fast On the third hand - I would be more than happy to contribute to building the community section, but I'm not sure if a PHP guru will be much help (as I'm assuming its built on Ruby) On Jul 21, 2:53 am, Richard Quadling <rquadl...@gmail.com> wrote: > On 20 July 2011 15:26, Sander Thalen <stha...@gmail.com> wrote: > > > > > > > > > > > I also recently posted on the Lighthouse ticket system. But no response. I > > started writing about the documentation, but also mentioned that state of > > the community and the future. This is what I wrote: > > > ------------ > > > I have a question about the API Documentation that is generally available on > > the website of Prototype (and just a little more). > > > The 'new' style documentation refers to the 1.7 documentation while the old > > one is (good as it is!) still available which Google is still indexing and I > > access it via my bookmarks. I try to use the new documentation now and then > > but for some reason I don't think it is nice to use. Also other developers > > tend to use the old one, over the new one. > > > I really believe in the Prototype library - but I also notice that the > > jQuery (for example) community is growing larger and larger and less people > > seem to be interested in Prototype. It would be great if Prototype would > > become more popular, so that the community grows, which hopefully supports > > development as well. I think this can be achieved by adding a Forum on the > > website, that is easily accessibly. Of course I use the Mailing List as > > well, but a Forum would be an easy way to access. This is however not the > > most important addition I think. > > > The amount of information in the Prototype API Documentation could use a > > little more.. documentation. This way more people can see how the full power > > and potential of Prototype can be unleashed and why this is such an > > interesting library. > > > A good example of what I believe that is a good manual, is the PHP manual. A > > semi-fixed format where you can find all the required information to quickly > > use the specific class/function. Especially the Examples are very handy. I > > know the Prototype documentation has examples, but for this new function > > Element.Offset only a little amount of documentation is present - actually I > > don't know how to use it (yet). > > > What are the plans for the documentation? Would it be possible to add > > examples myself? And also.. how does the Prototype team see the future > > regarding a community? > > > If this sounds like a cry for help, well.. maybe it is. But not 100% for me, > > but for the entire community! > > > Regards, > > Sander > > > ------------ > > As a member of the PHP Documentation team (an official title as PHP is > an Open Source Project and any one can contribute), I'd just like to > add my few pennies worth. > > 1 - The PHP documentation is stored as DocBook 5 XML -http://www.docbook.org/ > 2 - The documentation is stored on a SubVersion server > -http://svn.php.net/viewvc/phpdoc/ > 3 - We have many translations, some undertaken by a handful of people. > 4 - We have an online editing facility, allowing unregistered users to > correct/enhance the manual, with their changes being verified by an > existing member of the team -https://edit.php.net/ > 5 - We also allow unregistered users to add notes to the manual. These > aren't directly part of the official documentation, but can still be > present within the online manual, and in offline Windows CHM files > -http://www.php.net/download-docs.php > 6 - You can become a member when the quality of your changes are > acknowledged and supported by other members - a meritocracy. > 7 - All of this may be overkill for Prototype. > > Richard. > > -- > Richard Quadling > Twitter : EE : Zend : PHPDoc > @RQuadling : e-e.com/M_248814.html : bit.ly/9O8vFY : bit.ly/lFnVea -- 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.
