Hi all,

As you know, the new API docs[1] are generated via PDoc[2][3] from the
source code. Unfortunately, though, porting over the old docs[4] is a
non-trivial process, just because of the volumes involved and because
frankly the old docs were pretty out of date. (I cheerfully
volunteered to do it -- I'm not Core, I just help out sometimes and
help moderate the lists -- completely underestimating the size of the
task; and then my Real Job got Real Busy and I'm just not going to get
it done alone. In fact, I've done just about as much on it as I can.)

Now YOU, in just a few minutes per day, can dramatically help
Prototype's documentation by helping merge the old docs into the
source (and updating them to be current as we go). There are a bunch
of tickets in Lighthouse[5] related to merging the old docs in (that
link will automatically search for them for you).

The tickets have been divvied up into bite-sized chunks, so you can
dip in and out quite easily, it's not a big commitment!

Much of the work has already been done for you, by Tobie writing a
script to reach into Mephisto (the CMS that handles the old API docs
[and various other things]) and extracting the docs, automatically
converting much of their markup into the new PDoc format. Those .pdoc
files (which are just plain text) are attached to the tickets they
relate to. So a lot of this is just copy-and-paste into the relevant
source file.

It's easy to get involved, especially if you're a Mac OS, Linux, or
*nix user (but Windows users are welcome too!). Just:

1. Grab a copy of the the source:

$ git clone git://github.com/sstephenson/prototype.git
$ cd prototype

2. Build your local copy

$ rake dist
$ rake doc

(You may need to install the bluecloth ruby-gem. If you find you need
to install others, please post here so people know!)

3. Grab one of the "merge old docs" tickets[5] from Lighthouse

4. See if someone's already working on it (see the comments) and if
not, add a comment saying you're working on it

5. Make your changes to the source. Please do take time to make sure
that what you're doing is in keeping with the new PDoc formatting and
such.

6. Check them by building your docs again (rake doc)

7. Build a patch:

$ git add src/blah/blah.js  (e.g., the file you modified)
$ git commit -m "doc: blah blah blah [#123 state:resolved]"
$ git format-patch origin

(Note the "doc:" at the beginning of the commit line, and the "[#123
state:resolved]" at the end. The 123 should be the issue # of the
issue you're fixing.)

8. Upload the patch file to the ticket.

More info on getting the source and building patches and such on the
Contribute page[6].

Some things to look out for in the docs:

* Do the parameter names match the source?
* Do the parameters have their types?
* Are the examples correct?
* Are the examples...overdone, overly chatty, or unrealistic -- e.g.,
in need of pruning?
* Do all "Examples" headers use H5 (either by using an h5 element, or
by using five has marks: #####)?

[1] http://api.prototypejs.org
[2] http://pdoc.org
[3] http://groups.google.com/group/pdoc
[4] http://prototypejs.org/api
[5] 
https://prototype.lighthouseapp.com/projects/8886-prototype/tickets?q=merge+old+docs+state%3Aopen+state%3Anew&filter=
[6] http://prototypejs.org/contribute

If we all pitch in a few minutes here and there, we'll get the new
docs up-to-scratch in terms of information in no time!

Many thanks in advance to anyone who pitches in.

-- T.J. :-)
--~--~---------~--~----~------------~-------~--~----~
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