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

[Charlie Lowe]

Kieran Lal wrote:

> I like single sourcing but I think there may be some problems that  
> can not be automated away.  Consider these examples from the  
> documentation sprint.  Some documentation asks the reader to log on  
> and enable the module.  The problem is that the documentation the  
> users are reading is only available if the module is enabled, and  
> they can only read it if they have logged on with administrative  
> privileges.   So while that makes sense in the handbook, it doesn't  
> make sense in the context sensitive admin help documentation. 

Good point. Now you are talking :) This belongs in HowTo documentation, 
not in the basic introduction and overview of features, and would be 
part of documentation specs. There's no reason, IMHO, that the Drupal 
handbook can't be constructed in this way.


> Another example is the use of the admin >> module name >>  linking.    
> Those explicit instructions are fine for the handbook because they  
> are easy to follow.  But if the documentation is in Drupal itself  
> then you are much better off having a shorter description and a  
> relative link directly to the page you are talking about.

I'm not sure I completely agree with this assumption, but if this is the 
case, then it is possible to create documentation in the handbook that 
follows this rhetorical structure.

> 
>  From a usability standpoint I would like to think of the  
> introduction as a list of benefits to the user, and the overview of  
> features as a list of tasks they can accomplish.   I am hopefully,  
> only a few more hours away from having edited all 60 modules admin  
> help for consistency.   I tried where possible to have the first  
> paragraph describe the benefits of the module, and the second module  
> describe the tasks.   Then I provided an easily scannable list of  
> relevant links that users could use.

First off, this, as a documentation spec, would have been helpful up 
front when asked to participate in the sprint. Not only that, it would 
have been useful to discuss the spec in order to improve on the 
rhetorical strategy. I also think that it's possible to construct the 
documentation in the handbook somewhat along these lines so that the 
only thing that would have to be added would be the link to the handbook 
itself when moving to the guide.

But I think we agree somewhat here. The introduction, to me, should be a 
definition (in non geek terms) of what the module is so that it 
satisfies the newbiest audience--that person who is unfamiliar with what 
the module is or does. Your use of the term "list of benefits" is one 
good approach for how to think of this, although I see it as overall, 
most common benefits. Deciding what is common, what is best described 
most generally can be based on a lenght constraint--whatever is most 
important and fits within the description length we have in mind.

The feature overview should indeed be descriptions of the most commonly 
used features that our audience in this case should need. Those 
descriptions should enable the user to perform the most common tasks. We 
agree here. But we have to decide what that audience is more clearly and 
what their needs are even beyond the results of the usability study. For 
example, the forums documentation that you have now in the wiki is 
largely just a repeat of the rhetorical strategy of the incontext help:

http://dev.bryght.com/t/wiki/ForumHelp

Forums are being described in terms of containers, rather than in terms 
of forums and subforums with containers being a special case of how to 
use the forums, right now, making it a little more difficult to 
assimilate for those trying to understand what a forum is. In other 
words, given our audience (if I'm making the right assumption about our 
audience, which suggests we may need a better audience analysis 
writeup), it's missing part of the general description that should be 
available first before discussing what a container is.

> 
> When we created the new handbooks the titles were carefully chosen to  
> reflect the tasks the users were trying to accomplish by reading the  
> documentation.
> 
> Here are the list of titles: http://drupal.org/handbook/v2

Right. No problem with that, although I suspect that a better way to do 
this would have been to change the exisiting handbook rather than trying 
to create all new and moving around so much.

> But I haven't heard any opposition to getting links  
> to new handbook modules pages. Adding links would greatly improve the  
> doc teams ability to update documentation that users would benefit from.

Not sure what you mean by this?