[documentation] Barriers to entry...

[Ariane Khachatourians]

The thing with task-oriented user guides or help, is that when you start
getting more extensive documentation, it needs to cover more bases, and
that's why this has to be a well thought out process.

All completed Drupal sites work very differently once configured, and I
imagine that is part of the reason why the current documentation is more
geared towards explaining how things function and what is possible rather
than step-by-step and end-user targeted.

As someone who spent endless hours writing and updating customized end-user
manuals at my previous job, I know both how valuable that kind of tool is to
the users, but also how difficult it is to have any one guide apply to even
most use cases.

It is fairly obvious that a lot of people find the current system lacking
though, so we should certainly try and pinpoint exactly what is lacking, and
what specific changes can be made to ameliorate that.

So my suggestion here is along the lines of Jennifer's, which is that if you
have *specific* ideas or criticisms, please document them as issues, and
maybe we can declare a tag "D8help" or something of the sort.  And get some
of the actual needs nailed down so that when the D7 work settles, we have
something tangible to review and base our future discussions off.

Ariane



On Sun, Nov 15, 2009 at 11:24 AM, Nancy Wichmann <nan_wich at bellsouth.net>wrote:

>  Shai Gluskin wrote:
>
> > MS Office... probably the best built-in help system I've seen.
>
>
>
> I sincerely hope we can do better than that. Personally, I think it has a
> long way to go. But maybe that’s because I am a long time power user, so
> when I have a question, it’s usually a doozy.
>
>
>
> The best part of that to model is the task-oriented writing. Much of
> Drupal’s documentation is not task-oriented.
>
>
>
> When I was working with IBM mainframes (long ago, in a galaxy far away) we
> had a “User’s Guide” and a “User’s Reference” for most things. The Guide was
> lower level, and mostly task oriented, while the Reference was
> function-oriented, more like DO.
>
>
>
>
>
> Nancy E. Wichmann, PMP
>
> Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L.
> King, Jr.
>
> --
> 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/ae99a96d/attachment.html