[documentation] Barriers to entry...

[Steven Peck]

Minor history trivia.

The older built in 'help' that existed (and was removed prior to D6 or
5, I forget) was regarding the module and site administration side of
things.  Things the end user was not expected to see.  At the time
(and I think still) this was the way to go.  For the very reason that
Drupal is flexible, it's even harder to write generic 'end user help'
that works across a wide variety of differing site implementations.

There did exist a series of 'end user' pages in the handbook but the
real purpose of those pages was for site implementers to take and
customize to their needs and implement the relevant portions to their
own sites (not even sure if they still exist anymore).  This was true
when flexinode module came out and has become even more true as more
interesting cck implementations have come out.

So, when you talk about improvements in documentation, as Shai says,
be clear up front on where / which audience your suggested
improvements are focused on.

Steven

On Sun, Nov 15, 2009 at 12:04 PM, Shai Gluskin <shai at content2zero.com> wrote:
> 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/
>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>