[drupal-docs] Round 4 of documentation sprint Admin help: merging into the handbook

[Charlie Lowe]

The first thing to mention is that the goal of this is to integrate the 
admin/help text into the existing handbook, not to complete a 
restructuring/rewriting of the entire book which is to be the 
"Configuration and customization" book as part of the documentation 
sprint initiated to update admin/help. That's a big job. Consider this 
then a completion of the admin/help project rewrite which also makes 
strides in two directions:

1) it includes new documentation in the handbook for a lot of modules 
that was not there before.

2) it places the admin/help text into the handbook where we can work on 
it in the future.

As for the titles, they are currently organized randomly in the modules 
and features section: just by the name of the title whatever it might 
be. Using the module name plus a subtitle has two benefits:

1) It orders the modules in a way that facilitates searching for those 
that know the module name they are looking for.

2) It recognizes that user might not know the module name or might not 
remember. Without the subtitles, this would require all users to click 
on each link. Thus, the subtitles provide some information to assist 
those users in finding what they are looking for.

Granted, there may be an even better way to organize those titles other 
than just as core and contributed modules. This would be a task that 
whoever takes on reworking the entire section could take on.

As for rewriting the existing text to better integrate, the drupal-doc 
can certainly do that. But our first goal was to move in the admin/help 
text.


Kieran Lal wrote:
> 
> On May 23, 2005, at 9:12 PM, Kieran Lal wrote:
> 
> I'll try to address Charlie's, Djun's, Dries's, and Anisa's comments here.
> 
>> Hi, I am beginning round 4 of the Drupal admin help documentation 
>> sprint.   I figured it would take at least 5 revisions to make it 
>> work, so we are getting close to the end.
>>
>> Here's the plan:
>> 1) Change the handbook links for Drupal core to point to the existing 
>> relevant handbook pages.
>> 2) Change the titles of the  *Drupal handbook* 
>> <http://drupal.org/handbook> » *Administrator's guide* 
>> <http://drupal.org/node/257> » *Drupal modules and features* 
>> <http://drupal.org/node/279> to start with the module name: a brief 
>> phrase.
> 
> 
> Charlie, titles can begin with capital letters on the module name.
> 
> Djun, this section is not well organized.   By adding the module name to 
> the title the Drupal core module pages will be organized alphabetically 
> and therefore make for better searching.   A card sort is a good idea.  
> In the meantime we are settling on two top level categories, core 
> modules and contributed modules.  I believe the intention is to phase 
> the existing administration handbook into the configuration and 
> customization handbook by renaming the book and by re-organizing pages.  
> 
>> 3) Move the configuration and customization handbook contributed 
>> modules section: http://drupal.org/handbook/config/contribmodules to 
>> the existing handbook http://drupal.org/node/279 (Djun)
> 
> 
> Anisa, since we are no longer doing handbook version 2 we are moving the 
> pages already created for contributed modules into the existing 
> handbook, rather than create new pages.  There do not appear to be any 
> new handbook pages for contributed modules.
> 
>> 4) Move sprint admin help text to the top of the existing handbook pages.
> 
> 
> Djun, there are handbook pages for each of the modules in Drupal core.  
> Sometimes more than one.  We are basically just going to add the admin 
> help text to the top of those existing pages, so there's not need for 
> parallel new and old pages.  As Dries, indicated there is always 
> revisions if necessary.   
> 
>> 5) Move the old admin help that exists to a sub page of the handbook 
>> module page.
> 
> 
> Dries, the current admin event help text is 481 words long.  The new 
> admin help text is 192 words long.  The risk is that if we don't create 
> a sub page with the existing admin help we may lose a lot of valuable 
> information.  The editing of the handbook pages content is still a large 
> job and Charlie, Anisa, and I have to agree what the contents of a 
> handbook module page should be.
> 
>> 6) Review the admin help text for readability.
>> 7) Coordinate new handbook module writing instructions with Anisa and 
>> Charlie.
>> 8) If possible, change the relative links in the handbook, to bread 
>> crumbs format.  page >> page >> page.
> 
> 
> 9) Do a link search for all the existing module handbook pages.  As the 
> pages are renamed we are going to need go through the handbook and 
> discover if renaming the handbook pages has an adverse effect existing 
> handbook text.
> 
> For example search for pages that point to the blog module handbook 
> page: http://www.google.com/search?&rls=en&q=link:http://drupal.org/node/280 
> <http://www.google.com/search?&rls=en&q=link:http://drupal.org/node/280>.  
> Make sure the links still make sense when the page they are pointing to 
> is renamed.  Users who are new to a topic can get confused if they link 
> they click on is named differently than the title of the page.
> 
>>
>> As always, help is needed.
> 
> 
> Thanks for your comments.
> 
>>
>> Cheers,
>> Kieran
>>
>> -- 
>> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>>
>