Something I've not seen in these discussions is the api.drupal.org site. Simply comparing at a high level api.drupal.org & someplace like php.net:
api.drupal.org: each page has the routine source, number of times used by core, & comments that are rarely used. php.net: a description of the usage, inputs & outputs of a routine, 'commentary' about the routine, and verbose community comments of varying quality. Granted, php.net has its own issues, but at least it is useful. I never have php questions longer than it takes to look up the issue there. On the other hand, api.drupal.org is only useful to core developers. What about everyone else? Fixing that would go a long way towards making our documentation issues better. I advocate these forum solutions being proposed include rolling out the same ranking comment system for api.drupal.org. Sincerely, -Blake bsenft...@earthlink.net www.BlakeSenftner.com www.MissingUbercartManual.com On Feb 1, 2011, at 11:25 AM, Josh Koenig wrote: > I like the shape this discussion is taking. As few things: > > 1) I don't think the StackExchange model is really about "Support." It's > about "Answers." There's a non-trivial difference. While answers are helpful, > as are documentation, "support" is about getting specific help for your > specific problem. That's almost always got an ongoing human component to it. > > 2) I would really love to see the Forums improve as well! There's a huge > value in that use-case, even if it's not something that core developers use a > lot. They're popular! :) > > 3) No comment on how we govern the documentation process, but maybe the > mission of d.o in this context should be re-thought? The most definitive and > up to date documentation we have is embedded in the code and exposed via > api.d.o. The handbooks have a lot of stuff, but much of it lacks the same > quality. There's also an enormous amount of valuable howto and faq material > "out there" on other places in the internet. > > If the handbook were to re-tune the quality/quantity ratio, and focus more on > documenting the common use-cases and settled questions (as well as the > experience of first-timers) it could end up providing more value....
