[documentation] Barriers to entry...

[Shai Gluskin]

Folks,

A lot of good thinking is going on here...

I'd like to put some emphasis on something we all know but may not be
thinking about... I think it is important to disambiguate between
"help-text" and "documentation." "Help-text, in general, are very short
strings, often on forms or on other administrative interfaces that help
admins or content creators fill out a form or choose settings. It exists 'in
situ" right on the page where you are creating the content or making the
admin choices. Documentation, on the other hand, can be printed, in a book,
on a website (like d.o.'s handbook). I think the module help pages that we
are reformatting now is neither help-text nor documentation. It's closer to
documentation, but it's very, very, general and mostly not that useful.

Help-text suggested fixes for Drupal core are filed in the Drupal main issue
queue: http://drupal.org/project/issues/drupal. They are typically fixed one
at time. And you definitely don't need ANY coding skills to notice and
propose a change to a help-text problem. If there is consensus on the issue
about the proposed language being better, someone will make the patch for
you. (Note that if you have a problem with the handbook -one that can't be
fixed by clicking on "edit" on the page in question- you can file an issue
in the documentation issue queue at:
http://drupal.org/project/issues/documentation. It's almost always a good
idea to raise the issue here in the docs list serve before filing the issue
in the documentation queue).

This project of sprucing up the core module description help is raising
bigger issues. I think the biggest issue is do we want the central
repository of help to be encoded in Drupal or is it better outside of the
code. I am against big ideas that would expend a lot of energy trying to get
significant documentation into Drupal code. It would be lots of effort for
little payoff and very difficult to maintain.

I think that working on the handbook is where the biggest gains are likely
to be made. The limbo with the d.o. re-design has impacted negatively on the
handbook's evolution. Once the d.o. re-design launches, I think working on
the handbook will be a LOT more fun and I think we will make faster and more
coherent progress on it.

Shai


On Sun, Nov 15, 2009 at 2:34 PM, Ariane Khachatourians <
arianekhachatourians at gmail.com> wrote:

> 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/
>>
>
>
> --
> 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/27204fbc/attachment-0001.html