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

[Kieran Lal]

On May 12, 2005, at 11:34 PM, Charlie Lowe wrote:

> I think whether or not the documentation is hardcoded or not is up  
> to the development team.

I think the days of developers being in charge of the admin help  
documentation are fading fast.

27 out of 60 modules did not have administration help documentation.   
(14/31 core)

I have to revise these numbers as I found more help text later but  
you are looking at roughly 45%  of modules having no admin help  
text.  The docs team needs to take this responsibility on.

> This is sort of why I suggested a sort of single-sourcing approach.

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

>  developers might choose to include more (but we can leave that up  
> to them).

(With all due respect to developers)Or more likely, include nothing  
at all for the admin help.

> Then, when we update the documentation, we post an issue for  
> developers
> to plug it in as a revision to the admin/help. They take it from  
> there.
> Whether or not it is hardcoded in doesn't matter for us as  
> documenters.
> Developers can decide what is the easiest way to implement it. We just
> have to provide it.
>
> For an example, this piece of documentation for the sprint fits  
> that model:
>
> http://dev.bryght.com/t/wiki/BookHelp
>
> It has an introduction, overview of features, and a howto.

 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.

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

> This also gives us our plan for development. The introduction and the
> overview has to be done first. We add in howto's if they are available
> or we happen to be writing them anyway for some other purpose. But we
> don't worry about developing more docs until those are done first.
>
> We also may reach a point where we limit how much is included  
> there: how
> much "howto" and configuration tips, etc. More important than the  
> volume
> of documentation is that we arrive at a place where we can maintain  
> the
> documentation, be able to update it readily for new releases. So for
> instance, a documentation sprint at codefreeze for a new release,  
> where
> our first priority is to update all the introductions and overviews so
> that it can go into the admin/help.

Sure.  I feel we don't quite have unanimity on the length or content  
of admin help.  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.

Cheers,
Kieran

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