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

[Charlie Lowe]

Kieran Lal wrote:
> 
> 
> For all 60 of the modules admin help documentation we have added  
> links to the new handbook pages.    Currently there is either no  
> documentation in admin help or there are no links to further  
> documentation.   Having a link to each handbook module page from a  
> Drupal site allows the doc team to provide documentation directly to  
> users.   Connecting Drupal users directly to the work of the doc team  
> is a big deal.

Oh definitely. Linking to the handbook pages is a big plus :)

One way I look at this is sort of like an abstract or an executive 
summary with the lead documenation on the handbook pages (the 
introduction and/or overview of features) mirroring the admin/help and 
vice versa. So then a link back to the larger text makes a lot of sense.

However, I'm not convinced that the new handbook in terms of new pages 
for everything is a good thing. I remember that Dries has expressed some 
concern, too, about creating all the new pages instead of just revising 
the existing one's as needed and moving them where they need to go. Case 
in point: I'm in the middle of building documentation for a Drupal 
project that needs to go live now in the next few weeks. I'll have a new 
DrupalEd version of the one I created for Drupal 4.4 which will be used 
here at Purdue, distributed at a workshop, and made avaialble for 
download. It will likely include configuration tips and handouts from 
other teachers that are involved in giving the workshop. So the handbook 
is now useless to me since if I link to the old stuff, the links will 
rot. If I link to the new stuff, well there's nothing there yet.

I had also thought the plan was to create new handbook pages and copy 
them over, but that seems to be different from what you are suggesting. 
Still, same situation but a problem on your end. Those links in the 
admin/help you are creating will die.

This is just one of the reasons that it seems to me that the process for 
this has become too complex right now. If you'd like, I can outline how 
to simplify all of this in a separate post. I think the direction we are 
heading now is

a) taking too much effort
b) will be difficult to maintain
c) has so many workflow processes going on that it's taking away time 
from responding to and developing the docs themselves. For instance, I 
respond to writing *all the time*. LOL. I would be more than happy to 
give feedback on lots of documentation (such as the problem with 
defining forums in terms of containers, rather than forums as forums 
with containers as a special case), but we need clear processes and 
documentation specs to do so.
d) is trying to be representative of multiple approaches to 
documentation process and development when finding a unified approach 
that works for everyone is best. outlining everything is a must for 
doing this.

Charlie