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

[Kieran Lal]

On May 14, 2005, at 12:45 PM, Charlie Lowe wrote:
> http://joe.english.purdue.edu/~lowe/f04_2/files/docs/ 
> audience_analysis.doc
>
> Is this the kind of thing you are looking for?

Yes.  It made me realize I don't want to audience analysis myself :-)
>
> Maybe revising that list will help:

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.

> * 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).

> * Understanding where the original documentation meets those goals
> successfully.

Some of the documentation is quite good and provides a good level of  
detail on what the module is capable of.

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

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

Kieran
>
> Charlie
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>