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

Tue May 24 17:04:48 UTC 2005

IMHO I believe there should be a taxonomy for all the modules. 
Then some one looking for a solution to a problem would see all the modules
(Solutions) at one time.

Some other method could be used to distinguish between included and
contributed (not color, wouldn't show in print view) 

People don't look for modules, they look for solutions to there problems.

Focus on the benefits not the problems.

Regards
Ron

InterNet Marketing Resource Center
A Free Super Mart of Articles, Demos, Tutorials everything you need to
Succeed on the net.
www.inmrc.com 

-----Original Message-----
From: Charlie Lowe [mailto:cel4145 at cyberdash.com] 
Sent: Tuesday, May 24, 2005 10:37 AM
To: drupal-docs at drupal.org
Subject: Re: [drupal-docs] Round 4 of documentation sprint Adminhelp:
merging into the handbook

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