[documentation] Barriers to entry...

[Lee Hunter]

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.

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.

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".

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.


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.

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 ..."

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.

Lee


2009/11/14 Jennifer Hodgdon <yahgrp at poplarware.com>

> Regarding the process and getting non-programmers involved in the help
> screens and text in general in Drupal....
>
> For this patch we're working on -- there isn't time to get a new
> process in place, because of the time frame. But I agree that there is
> a VERY high perceived barrier for non-programmers to help with
> documentation in Drupal. This is also a problem for designers who
> might want to contribute to themes.
>
> I do have a couple of suggestions for how non-programmers can get
> involved and help out with Drupal documentation (more at
> http://drupal.org/node/540308):
>
> a) Non-programmers can definitely contribute to the Handbook
> documentation on drupal.org. There is a suggested list of ways to
> contribute to the Handbook at http://drupal.org/node/302146 and none
> of those ideas requires you to "roll patches", work in PHP, etc.
>
> b) If you see problems in the help text or user interface text within
> Drupal, you can file an issue. Even if you do not know how to create a
> patch, you can still give before/after text suggestions, and someone
> else can create the patch. To do that:
>   - Click on "Create Content" on the sidebar on drupal.org
>   - Choose "Drupal" as the project
>   - Choose the Drupal version. Note that for right now, pretty much
> only 7.x issues will be addressed -- it is REALLY difficult to get
> text changes into 6.x at this point, if not possible.
>   - Choose component "user interface text" or "documentation", as
> appropriate.
>   - Choose category "bug report" -- text being wrong, missing, or
> unclear is a bug, not a feature request or task.
>   - Make up a clear title and description, and submit your issue.
>
> c) To help with existing issues, search the issue queue for the Drupal
> project, component "documentation" or "user interface text" or tag
> "Help text" or tag "ui-text". Be aware that most of the issues filed
> under component "documentation" are issues with the in-line programmer
> API documentation of functions in the source code (displayed on
> api.drupal.org), so if you are not a programmer, these will not be
> things you will probably want to work on. Even if you cannot write
> patches, you can still review patches and make suggestions on how to
> improve text, by commenting on issues.
>
>
> Thoughts?
>
> I was thinking maybe it would be a good idea to propose a session at
> DCSF to get non-programmers up to speed on patching, but then I read
> one of the commenters saying "no inclination" to learn that...
> Definitely, the formatting needed for the help docs is a barrier
> itself. There was a move to improve the help system for Drupal 7 (make
> it into plain HTML files), but it didn't get into core.
>
>    -- Jennifer
>
> --
> Jennifer Hodgdon * Poplar ProductivityWare
> www.poplarware.com
> Drupal, WordPress, and custom Web programming
>
> --
> 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/20091114/8065b61d/attachment.html