Folks,<br><br>A lot of good thinking is going on here...<br><br>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.<br>
<br>Help-text suggested fixes for Drupal core are filed in the Drupal main issue queue: <a href="http://drupal.org/project/issues/drupal">http://drupal.org/project/issues/drupal</a>. 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: <a href="http://drupal.org/project/issues/documentation">http://drupal.org/project/issues/documentation</a>. 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).<br>
<br>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.<br>
<br>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.<br>
<br>Shai<br><br><br><div class="gmail_quote">On Sun, Nov 15, 2009 at 2:34 PM, Ariane Khachatourians <span dir="ltr"><<a href="mailto:arianekhachatourians@gmail.com">arianekhachatourians@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">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. <br>
<br>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.<br>
<br>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.<br>
<br>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.<br><br>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.<br>
<font color="#888888">
<br>Ariane<br><br><br><br></font><div class="gmail_quote"><div><div></div><div class="h5">On Sun, Nov 15, 2009 at 11:24 AM, Nancy Wichmann <span dir="ltr"><<a href="mailto:nan_wich@bellsouth.net" target="_blank">nan_wich@bellsouth.net</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div><div></div><div class="h5">
<div link="blue" vlink="purple" lang="EN-US">
<div><div>
<p class="MsoNormal"><span style="font-size: 10pt;">Shai
Gluskin wrote:</span></p>
<p class="MsoNormal"><span style="font-size: 10pt;">>
</span>MS Office... probably the best built-in help system I've seen.</p>
<p class="MsoNormal"> </p>
</div><p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">The best part of that to model is the task-oriented writing.
Much of Drupal’s documentation is not task-oriented.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p><div>
<p class="MsoNormal"><span style="color: rgb(31, 73, 125);"> </span></p>
<p class="MsoNormal"><span style="color: rgb(31, 73, 125);"> </span></p>
<div>
<p class="MsoNormal"><span style="font-size: 14pt; font-family: "Comic Sans MS"; color: fuchsia;">Nancy E. Wichmann, PMP </span><span style="font-size: 14pt; color: rgb(31, 73, 125);"></span></p>
</div>
<p class="MsoNormal"><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(31, 73, 125);">Injustice anywhere is a threat to justice everywhere. -- Dr.
Martin L. King, Jr</span><span style="font-size: 10pt; color: rgb(31, 73, 125);">.</span><span style="font-size: 11pt; color: rgb(31, 73, 125);"></span></p>
</div></div>
</div>
<br></div></div><div class="im">--<br>
Pending work: <a href="http://drupal.org/project/issues/documentation/" target="_blank">http://drupal.org/project/issues/documentation/</a><br>
List archives: <a href="http://lists.drupal.org/pipermail/documentation/" target="_blank">http://lists.drupal.org/pipermail/documentation/</a><br></div></blockquote></div><br>
<br>--<br>
Pending work: <a href="http://drupal.org/project/issues/documentation/" target="_blank">http://drupal.org/project/issues/documentation/</a><br>
List archives: <a href="http://lists.drupal.org/pipermail/documentation/" target="_blank">http://lists.drupal.org/pipermail/documentation/</a><br></blockquote></div><br>