[documentation] Barriers to entry...

[Shai Gluskin]

Lee and Jennifer and all,

I agree with Jennifer that the online handbook is the best way to go. This
current effort will make Drupal look slicker and it will be of some marginal
help, but it doesn't tackle the bigger issue.

For D8 I think we should advocate for A LOT more references within the
Drupal install to d.o. handbook pages. That gives people good references
inside the ap, but allows the info to be current since handbook pages are
constantly up-datable, and there is no technical barrier to entry.

Something I thought of in the shower last night..

I love Mac OS X... terrible built-in help system
I hate MS Office... probably the best built-in help system I've seen.
I love Drupal... I've attempted a few times to use the built-in help system
and found it unsatisfying. Maybe three times in 3 years, and I'm probably
seeking Drupal info every single one of those days.

In short, I think the handbook is the way to go...

And that's not to minimize this push to do a modest improvement to the built
in help system. I'm just alerting non-coders that I don't think this is
really where the action is.

Shai

On Sun, Nov 15, 2009 at 10:37 AM, Jennifer Hodgdon <yahgrp at poplarware.com>wrote:

> Lee Hunter wrote:
> > We're calling this a "help" system but that's not at all what's being
> > written. It would be much more accurate to call it a "Module Reference".
> >
> > Help system content is normally all about the user - what the user wants
> to
> > achieve and the tasks that they want to perform [...]
>
> I agree, Lee: Definitely the main module pages that we are editing are
> a module reference and not a user guide. The other entries in
> hook_help() implementations (which are help text that can be displayed
> on individual screens the module provides) are more in the line of
> "user guide", but they certainly don't constitute a full user guide.
> And hook_help() is never going to be a good vehicle for creating a
> full user guide.
>
> I will just note that the effort to revamp the current Drupal help
> system (perhaps in line with the Advanced Help contrib module) failed
> for D7 (I'm not familiar with exactly why)... and now is definitely
> the time to start thinking about what architecture would make sense
> for D8.
>
> But I am not sure we want to ship a user guide with Drupal at all,
> really -- maybe we should stick with the on-line Handbook (or some
> small, official subset) as the official user guide. This would have
> several advantages:
> - Non-coders can edit.
> - Few barriers to doc writers to contribute.
> - Much more dynamic than Drupal releases. Anything distributed with
> Drupal has to be translated into many languages, which pretty much
> means it is set in stone once a major release is out, and cannot
> (except for major bugs) be revised for minor Drupal versions.
> - Searchable via search on d.o as well as web search engines.
> - Can recommend contrib modules to achieve goals that are
> difficult/impossible with just core Drupal.
>
> Thoughts?
>
>    --Jennifer
>
> --
> Jennifer Hodgdon * Poplar ProductivityWare
> www.poplarware.com
> Drupal, WordPress, and custom Web programming
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20091115/f8090a97/attachment.html