[drupal-docs] Dead links in documentation

[Angie Byron]

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

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