[drupal-docs] Idea - move help text out of code into database

[Charlie Lowe]

Kieran Lal wrote:
> 
> Let me take a quick try at this and I hope others will jump in.
> 
>>* Understanding the target audience for the documentation. The  
>>audience
>>may be composed of primary and secondary audiences. Usability  
>>studies of
>>previous documentation are useful in definining the audience.
> 
> 
> Web site administrators I would say are the core Drupal audience.   
>  From a CivicSpace perspective we are interested in a less  
> technically savvy audience member and instead we are focused on  
> community leaders who are trying to organize their communities.    
> That can be a pretty big gap between those audiences.

I would say that both are audiences for both Drupal and CivicSpace but 
that the balance is definitely weighted more heavily one way or the 
other. Then again, in terms of writing documentation since CivicSpace is 
now working through Drupal CVS (at least I think that is what I've 
seen?), then the CivicSpace audience is the Drupal audience.

I would say, though, that the primary audience for the documentation are 
newbies to administering sites since many more experienced web site 
administrators can figure most of this out on their own. The 
documentations is more important to the less savvy group; more of a 
convenience to the more tech savvy. So the website administrators are a 
secondary audience. We write for the first, and as long as it's 
informative, concise, provides link to other documentation, and is 
scannable, it can still be useful to the more experienced, secondary 
audience.

> 
> 
>>* Understanding the goals for the documentation, how it is supposed to
>>meet the needs for that audience, as well as in the case of the
>>admin/help section, constraints on providing that documentation
>>(difficulty in encoding longer texts). What is the primary focus  
>>for the
>>document? Any secondary focus?
> 
> 
> Help them administer the module.  Users probably want to enable, then  
> troubleshoot, configure, and then learn how to use a module, in that  
> order. But that's SWAG(Scientific Wild A** Guess).

I would add:

* Introduce them to the module; the admin help will function as a place 
for people to figure out what the hell is the module they just turned on 
:) This is actually important because in certain circumstances if it 
doesn't function well enough to give them a quick glimpse of what the 
module is and what it can do, they will simply turn it off.
* Act as a quick reference for those that are already a little familiar 
with the module--negates the need to "remember" how to do everything 6 
months later when a user goes back to reconfigure a module again or when 
the module has changed between Drupal versions.


Secondary global goals for all of admin/help

* Reduce the common perception that Drupal is difficult to learn at first.
* Reduce support requests to the main community.

These suggest that perhaps we should query people who frequently provide 
basic configuration support and ask them to review the docuemtnation to 
see if any common configuration issues are being overlooked that could 
be included. If we could find even a dozen quesitons that are being 
asked all the time which are not addressed in the admin/help but could 
be, we could have a little impact on these items above.

  >
>>* Understanding where the original documentation fails to meet  
>>those goals.
> 
> 
> I think 45% of the documentation does not exist.  It does not focus  
> on benefit and tasks that are possible.  It does not provide context  
> links to help users complete tasks.  Administration links for modules  
> are scattered everywhere and that leaves users guessing where to  
> administer a module.  For example, I have probably discovered 10%  
> more administration interfaces because I was forced to read the code  
> and realize "They put administer there???".

Also, some of it is also very techie in choice of content and language 
(advanced stuff is covered sometimes, basic configuration not). Some of 
it could use better structuring (for example, key points are not 
highlighted first). And because some of it is out of date, it's highly 
likely that it's not all accurate.

> 
> 
>>* Strategies for revising the documentation to meet it's failings  
>>while
>>preserving what it does successfully (sometimes, this may include some
>>tradeoffs dependent on other constraints).
> 
> 
> Well, your strategy or my strategy ;-)
> 
> Write a sample, establish guidelines, build consensus[optional], push  
> off the details to the handbook, write a bunch of drafts, review,  
> edit, repeat.  Check in. Hope the developers accept your patches.

* Watch for techie language. When possible, use language accessible to 
the newbies that are not experienced website administrators. A good way 
to think about it is for the documentation writer to imagine that they 
are writing instructions for a friend or relative who is comfortable 
using email, surfing the web, and using basic desktop applications, but 
does not know much at all--if anything--about administering and 
configuring web applications but is interested or motivated to learn. 
(good to add something like this to admin/help writing instructions)

* Be sure to review alternative documentation since it may remind the 
documentation writer of features that need to be mentioned (I used my 
students documentation in this way and it reminded me to include a few 
things).

* Be sure to check very carefully for accuracy. Any inaccurate 
information can sometimes frustrate users more than no information.

* Get people that commonly answer support questions on CivicSpace and 
Drupal to review the documentation. Particularly, find some people that 
are not coders or developers, that are closer to the newbie audiences 
that we imagine. I tend to think that they are more likely to be able to 
*think* like a newbie non-developer than a developer is.

Charlie