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 <[email protected]> wrote:
On 20 July 2011 15:26, Sander Thalen <[email protected]> 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 [email protected]
.
To unsubscribe from this group, send email to [email protected]
.
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 [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/prototype-scriptaculous?hl=en.
