Plus one from me too. I agree there should be an easy way for "writing in the margins" (as Walter put it). I wouldn't encourage allowing those pages to be used for help requests (which could get overwhelming for a reader to slog through), but like the php.net docs, neat solutions and gotchas related to the page's topic. Good comments could be incorporated into the docs. It's a low-commitment way to encourage contributions (w/o the need for git, patches, etc.)
TAG On Jul 21, 9:42 pm, Walter Lee Davis <[email protected]> wrote: > 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 -- 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.
