[documentation] Barriers to entry...

[Jennifer Hodgdon]

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