[drupal-docs] Dead links in documentation

[Kieran Lal]

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