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.

Walter


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 .


--
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.

Reply via email to