On 2/1/2011 11:25 AM, Josh Koenig wrote:
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.
The purpose of api.drupal.org is to be a reference for Drupal's
functions and the module/theme programming API.
The purpose of the online documentation on Drupal.org is to provide
how-to and tutorials. In-code documentation comments can't really be
expected to do that, IMO, and the target audiences for these two types
of doc is not usually remotely the same.
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....
We'd love some help with that! We can always use more volunteers to
organize and write the online documentation, and without volunteers
who both know the subject matter and can write about it (or edit what
others have written), the online doc will not improve.
There is also a proposal you might be interested in at:
http://drupal.org/node/1031972
which would create a set of pared-down, official documentation (for
core and contrib), maintained on help.drupal.org, translated into
various languages by the translation team, and available for import as
the in-line help in a Drupal site. That proposal is in its infancy --
right now just trying to nail down the specifications.
--Jennifer
--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal web sites and custom Drupal modules
