[documentation] Barriers to entry...
Steve Kessler
skessler at denverdataman.com
Sun Nov 15 15:42:40 UTC 2009
I think that is critical that there is some amount of help that ships with
Drupal. But this could be 2 or 3 sentences and a link to a page. Does the
research from D7UX tell us anything that we should take into account?
Thanks,
Steve
Steve Kessler
Denver DataMan
303-587-4428
-----Original Message-----
From: Jennifer Hodgdon [mailto:yahgrp at poplarware.com]
Sent: Sunday, November 15, 2009 8:38 AM
To: A list for documentation writers
Subject: Re: [documentation] Barriers to entry...
Lee Hunter wrote:
> 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 [...]
I agree, Lee: Definitely the main module pages that we are editing are
a module reference and not a user guide. The other entries in
hook_help() implementations (which are help text that can be displayed
on individual screens the module provides) are more in the line of
"user guide", but they certainly don't constitute a full user guide.
And hook_help() is never going to be a good vehicle for creating a
full user guide.
I will just note that the effort to revamp the current Drupal help
system (perhaps in line with the Advanced Help contrib module) failed
for D7 (I'm not familiar with exactly why)... and now is definitely
the time to start thinking about what architecture would make sense
for D8.
But I am not sure we want to ship a user guide with Drupal at all,
really -- maybe we should stick with the on-line Handbook (or some
small, official subset) as the official user guide. This would have
several advantages:
- Non-coders can edit.
- Few barriers to doc writers to contribute.
- Much more dynamic than Drupal releases. Anything distributed with
Drupal has to be translated into many languages, which pretty much
means it is set in stone once a major release is out, and cannot
(except for major bugs) be revised for minor Drupal versions.
- Searchable via search on d.o as well as web search engines.
- Can recommend contrib modules to achieve goals that are
difficult/impossible with just core Drupal.
Thoughts?
--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/
More information about the documentation
mailing list