On Jul 21, 2011, at 8:32 PM, Jason wrote:
I agree with both Richard and Sander - and there might be a middle
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)
The current documentation (1.7) is generated directly from the source
code using a tool written by one of the core guys -- I think it's
called jsDoc or something like that. Anyway, it's just static HTML,
I think that if there was enough energy for moderation, or some sort
of community moderation system, that a great add-on to the site would
be something like Disqus, so the user comments and corrections could
be added to the mix. That's the thing I really love about the PHP
site, and miss in other languages. It's an annotated encyclopedia that
has lots of interesting stuff written in the margins by everyone else
who ever used it. I can't count the number or really hard problems I
was able to solve by looking at someone's example code in the comments.
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
started writing about the documentation, but also mentioned that
the community and the future. This is what I wrote:
I have a question about the API Documentation that is generally
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
but for some reason I don't think it is nice to use. Also other
tend to use the old one, over the new one.
I really believe in the Prototype library - but I also notice that
jQuery (for example) community is growing larger and larger and
seem to be interested in Prototype. It would be great if Prototype
become more popular, so that the community grows, which hopefully
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
well, but a Forum would be an easy way to access. This is however
most important addition I think.
The amount of information in the Prototype API Documentation could
little more.. documentation. This way more people can see how the
and potential of Prototype can be unleashed and why this is such an
A good example of what I believe that is a good manual, is the PHP
semi-fixed format where you can find all the required information
use the specific class/function. Especially the Examples are very
know the Prototype documentation has examples, but for this new
Element.Offset only a little amount of documentation is present -
don't know how to use it (yet).
What are the plans for the documentation? Would it be possible to
examples myself? And also.. how does the Prototype team see the
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!
As a member of the PHP Documentation team (an official title as PHP
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
3 - We have many translations, some undertaken by a handful of
4 - We have an online editing facility, allowing unregistered users
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.
aren't directly part of the official documentation, but can still be
present within the online manual, and in offline Windows CHM files
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.
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 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
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 firstname.lastname@example.org.
To unsubscribe from this group, send email to
For more options, visit this group at