PDoc documentation modification

[Bertrand]

Hi,

I was not too happy about the fact that the new version of the
documentation wasn't on par with the old one in terms of examples and
coverage. So I dove into github and began tackling the issue (the docs
are open source after all).
I wanted to send a tiny modification at first and my goal was to add
more modifications once the first pull request for the docs would get
approval. I then proceeded to enrich the docs for src/lang/array.js
(more to give the whole process a shot and see if I was doing things
properly). It's been around two weeks and still no feedback on it.
I was initially enthusiast about it all and really willing to get out
of my usual "consumer" way to become a proactive contributor.

With the severe lag in the answer from the devs, I have to admit to I
am a tad discouraged now. The new doc system was supposed to make it
easier for people to contribute, to surf on the community effort and
make the whole Prototype ecosystem kick ass. If it takes weeks for
someone to get something upstream, we're failing doing just that.

Now I am not naive either, I know you guys are busy with new features,
working very hard on your spare time to keep the library on the front
line at a time where jQuery is getting the best press and where Google
is delivering in the JS library department, but aren't we all?
Prototype users willing to give a hand have jobs too, they have
families, they're not familiar with the whole shebang and yet they're
trying. So please make it easy for them to help with the more tedious
tasks so that you guys can concentrate on what you've been excellent
at for a few years now: making Prototype the best JS library around.

[Tobie Langel]

Hi.

I understand your frustration.

TJ who was handling the doc up until now has very recently resigned.

We haven't found anyone to replace him in this role yet.

Until then, you might see some fluctuations in how fast these changes
are pulled upstream.

Would you mind posting a link to these changes so I can look at them
in the meantime?

Best,

Tobie

[T.J. Crowder]

Hi,

Sorry to hear about your bad experience. I didn't even know about your
submitting the patch (but then, I'm not Core). As a Prototype user, I
thank you for trying and hope you'll try again.

We're trying to bring the docs up to the old standard, and beyond; in
fact, I just posted a thread[1] about this. I was trying to do it on
my own, having foolishly thought it would be "a few hours" of work.
20+ hours of work later (fighting with tool issues most of the way)
I'd made a dent, but still had a massive distance to go, and frankly I
just ran out of time -- work that pays the mortgage took precedence. :-
(

So a few days ago I created a bunch of bite-sized doc tickets[2] in
Lighthouse so that we can throw this open to everyone without
duplication of effort (your array stuff may well have duplicated my
array work, for instance). More in that thread[1], but basically,
Tobie wrote a tool to extract the old docs from the old CMS and
reformat them a bit into mostly-PDoc format. So each of those bite-
sized tickets has the unedited auto-converted PDoc, and just needs
intelligent merging into the source and updating.

Once someone can successfully build the docs locally, each ticket is
designed to be about 15-30 minutes of work. There are 72 of them. Mike
Rumble has been chipping away at them, but he needs help.

[1] http://groups.google.com/group/prototype-scriptaculous/browse_thread/thread/5a03323af91f531b
[2] https://prototype.lighthouseapp.com/projects/8886-prototype/tickets?q=merge+old+docs+state:open+state:new&filter=

Thanks again,
--
T.J. Crowder
Independent Software Consultant
tj / crowder software / com
www.crowdersoftware.com