--
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-s...@googlegroups.com.
To unsubscribe from this group, send email to prototype-scripta...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/prototype-scriptaculous?hl=en.
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
>
> 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)
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,
CSS and JavaScript (naturally) once that tool is done.
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.
Walter
On Jul 21, 2011, at 8:32 PM, Jason wrote:
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)
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, CSS and JavaScript (naturally) once that tool is done.
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.
-- Bill Drescher william {at} TechServSys {dot} com
Walter
it works, it works well
and it's a great
base on which to build complex apps. If the developers decide to not
make any more upgrades we'd still have a great tool. I think of it as
a house foundation and what I build on top is the house itself.
If
the guy that laid the foundation decided to retire, it doesn't affect
my house.
volunteers who could project manage, do good design/CSS work, design a
framework that allowed 'widgets' to share a common base/communicate,
program, establish standards and so on, then with some effort we could
have a great tool with great add-ons. Imagine how simple things would
be if all Prototype widgets shared the same CSS classes and usage.
I'm willing to be a part of such a group.