I appreciate that it's not practical to inject some new steps into the process at this point in time. The important thing is that it gets done.<br><br>There is one other thing, though, that I have a problem with. I hesitate to bring this up, because again it may be a bit late to deal with but it is a really important ussue so I think it's worth bringing up any time. Actually, I did try to raise this point when the new Help system was being developed but I couldn't get any traction. However, since we're talking about help, here's my concern, for what its worth.<br>
<br>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".<br><br>Help system content is normally all about the user - what the user wants to achieve and the tasks that they want to perform whereas this content that's being developed is really describing the architecture of the software itself (here are the modules and here's what they do), information which is of very limited value to the user. It generally wouldn't appear at all in a typical Help system and if it did, it would be in the final section, as an appendix. <br>
<br>I know that there will be links here and there to various admin pages but that still isn't what the user would expect to see in Help. The Node module example really illustrates my point. The node module is merely part of the architecture, whereas most users will open the Help in the hopes that they will learn how to perform a specific content-related task or reach a content-related goal. How do I add a page? Manage content? I don't care what the software is doing, I'm only interested in what I'm trying to do.<br>
<br>Having said, for better or worse, we've already decided to go down this module-centric road with D7 so I don't think there's any way of changing the way things are structured. But I do think, as this new content is being written, we can start incorporating this principle of writing from the user's perspective rather than the module developer's perspective. Rather than write "The x module does this that and the other thing" start off with something like this: "When the foobar module is enabled, you can create an x and manage a y. " and for something like the Node module, keep the same pattern but change the wording to something like "The node module is always enabled. It is the part of Drupal that enables you to create and manage content. To add new content, click ... To manage content click ..."<br>
<br>It may be a long time before we make the inevitable step of structuring the Help around the user - perhaps not till D8 or 9, but there's no reason why we can't start writing that way immediately.<br><br>Lee <br>
<br><br><div class="gmail_quote">2009/11/14 Jennifer Hodgdon <span dir="ltr"><<a href="mailto:yahgrp@poplarware.com">yahgrp@poplarware.com</a>></span><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Regarding the process and getting non-programmers involved in the help<br>
screens and text in general in Drupal....<br>
<br>
For this patch we're working on -- there isn't time to get a new<br>
process in place, because of the time frame. But I agree that there is<br>
a VERY high perceived barrier for non-programmers to help with<br>
documentation in Drupal. This is also a problem for designers who<br>
might want to contribute to themes.<br>
<br>
I do have a couple of suggestions for how non-programmers can get<br>
involved and help out with Drupal documentation (more at<br>
<a href="http://drupal.org/node/540308" target="_blank">http://drupal.org/node/540308</a>):<br>
<br>
a) Non-programmers can definitely contribute to the Handbook<br>
documentation on <a href="http://drupal.org" target="_blank">drupal.org</a>. There is a suggested list of ways to<br>
contribute to the Handbook at <a href="http://drupal.org/node/302146" target="_blank">http://drupal.org/node/302146</a> and none<br>
of those ideas requires you to "roll patches", work in PHP, etc.<br>
<br>
b) If you see problems in the help text or user interface text within<br>
Drupal, you can file an issue. Even if you do not know how to create a<br>
patch, you can still give before/after text suggestions, and someone<br>
else can create the patch. To do that:<br>
- Click on "Create Content" on the sidebar on <a href="http://drupal.org" target="_blank">drupal.org</a><br>
- Choose "Drupal" as the project<br>
- Choose the Drupal version. Note that for right now, pretty much<br>
only 7.x issues will be addressed -- it is REALLY difficult to get<br>
text changes into 6.x at this point, if not possible.<br>
- Choose component "user interface text" or "documentation", as<br>
appropriate.<br>
- Choose category "bug report" -- text being wrong, missing, or<br>
unclear is a bug, not a feature request or task.<br>
- Make up a clear title and description, and submit your issue.<br>
<br>
c) To help with existing issues, search the issue queue for the Drupal<br>
project, component "documentation" or "user interface text" or tag<br>
"Help text" or tag "ui-text". Be aware that most of the issues filed<br>
under component "documentation" are issues with the in-line programmer<br>
API documentation of functions in the source code (displayed on<br>
<a href="http://api.drupal.org" target="_blank">api.drupal.org</a>), so if you are not a programmer, these will not be<br>
things you will probably want to work on. Even if you cannot write<br>
patches, you can still review patches and make suggestions on how to<br>
improve text, by commenting on issues.<br>
<br>
<br>
Thoughts?<br>
<br>
I was thinking maybe it would be a good idea to propose a session at<br>
DCSF to get non-programmers up to speed on patching, but then I read<br>
one of the commenters saying "no inclination" to learn that...<br>
Definitely, the formatting needed for the help docs is a barrier<br>
itself. There was a move to improve the help system for Drupal 7 (make<br>
it into plain HTML files), but it didn't get into core.<br>
<br>
-- Jennifer<br>
<br>
--<br>
Jennifer Hodgdon * Poplar ProductivityWare<br>
<a href="http://www.poplarware.com" target="_blank">www.poplarware.com</a><br>
Drupal, WordPress, and custom Web programming<br>
<font color="#888888"><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>
</font></blockquote></div><br>