[drupal-docs] Dead links in documentation

[Kieran Lal]

On Sep 23, 2005, at 1:46 PM, Angie Byron wrote:

> This is just an idea, but what if the paths in the Drupal.org  
> module handbook pages were coded thusly:
>
> <strong class="admin-help-link">administer >> help</strong>
>
> This way on Drupal.org, these would just show as bold text  
> indicating menu selections, and not as broken links.
>
> Then, a parser could be written which would check for the string  
> 'admin-help-link' and then get to parsing the path from there.
>
> I could probably work up a proof-of-concept thing this weekend if  
> this would at all be a desirable option. I realize initially  
> changing all the handbook link texts would be a bit tedious/ 
> annoying, but it would remove that usability barrier and also allow  
> the normal module documentation to be auto-generated (in theory ;)).

Just to be clear changing all the admin links wouldn't happen unless  
someone stepped up to spend several hours to implement it.

With that said  a prototype would help.

Kieran

>
> -Angie
>
>
> Kieran Lal wrote:
>
>> On Sep 23, 2005, at 5:57 AM, Kobus Myburgh wrote:
>>
>>> Comments, suggestions or alternative solutions anybody?
>>>
>> This is very much an imperfect solution.  There are now about 70  
>> administration help pages in the Drupal handbook.  This is was the  
>> single most requested feature in a survey of 200 Drupal users.
>> We made the decision to single source this documentation on  
>> Drupal.org and then generate Administration help as code from  
>> those pages.    Unfortunately, until a developer steps forward and  
>> codes a solution to create administration help code from the  
>> handbook we need to keep links inside the single source.   This is  
>> absolutely annoying.   I understand.
>> Here is what my scripts do:
>> 1) Generate a list of urls for the handbook module pages.  Turns  
>> this: aggregator, archive, block, into http://drupal.org/handbook/ 
>> modules/aggregator,  http://drupal.org/handbook/modules/archive, ...
>> 2) wget's the list of urls so I have the pages local.
>> 3) run structured grep on handbook module pages to get just the  
>> core page and not the blocks etc.
>> 4) For each page take a list of relative url's and generate an  
>> array of variable names mapped to urls.
>> 5) For each page create the tfunction which has a list of of  
>> variables mapped to urls for each module.
>> 6) For each page convert the relative urls into variables for the  
>> tfunction
>> 7) For each page concatenate the "case: admin/help"statement with  
>> the core text with the links listed in a tfunction statement
>> 8) For each page add the paragraph "For more information read  
>> the ....modulename handbook page" and link to the Drupal handbook.
>> Now you have to put in the module and create a patch.   I would  
>> estimate the first time we created these patches it took about 20  
>> hours to clean up the source documentation, create the patches and  
>> test all the links.   It's a lousy boring job and nobody wants to  
>> commit the time to do.
>> The only thing worse is knowing that thousands of Drupal users can  
>> not figure out you administer page content type at administer >>  
>> content >> configure >> content types >> configure page.
>> If you don't have the absolute links you are going to have to keep  
>> a separate table with all the paths to generate the relative links  
>> when you create the patches.    That means looking up adminster >>  
>> content >> configure >> content types >> configure
>> and figuring out the path is: node/configure/types/page
>> You need to do this in a scalable way so that we can have a list  
>> of all the links for at least the 70 modules and we should grow to  
>> over 200 modules.
>> Developers are welcome to code this.
>> Cheers,
>> Kieran
>>
>>>
>>> Regards,
>>>
>>> Kobus
>>>
>>> [1] http://drupal.org/handbook/modules/poll
>>>
>>>
>>> -- 
>>> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>>>
>>>
>>>
>> --[ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>>
>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>
>