[documentation] Links to module pages from contributed modules

[Boris Mann]

On 15-Jan-06, at 9:19 AM, Kieran Lal wrote:

> On Jan 15, 2006, at 1:05 AM, Boris Mann wrote:
>> On 14-Jan-06, at 11:48 PM, Kieran Lal wrote:
>> I'm not clear on what you're saying. How does this break admin help?
>>
>> Also, the comment seems to be only about related modules (which I  
>> agree could be handled by tags)...I believe each of those pages  
>> needs a link to the project page, so that people can go directly  
>> to downloading instead of having to search.
>>
>> related modules +/- ?
> This document is a single source for documentation for both the  
> handbook and the administration >> help pages.  I have always been  
> concerned that we do not include content that is inconsistent with  
> viewing these pages as part of the administration help inside a  
> Drupal site.  e.g. enable this module at administration >> help  
> doesn't make sense because it's already enabled.  I am not sure  
> that related modules belongs in the administration help for that  
> page, but I do think it has a place somewhere else.
>>
>> link to download +/- ?
> Versioning is important and has been identified as a top issue in  
> the Drupal Administration user experience survey.

Sorry...link to project page, not a direct download. It's insane that  
you can browse the documentation...but then have to go to the  
download section and browse all over again to try and find the  
mysterious module that was developed. Links need to go in both  
directions -- from docs to project pages and project pages to docs.

> We have 80 or so modules in a consistent format right now.  We have  
> published guidelines on what the format is going to be for  
> Administration Help for modules.  Please don't go and change just a  
> few to be a new format.  It causes confusion and inconsistency.

Hmmm...ouch. So I can't improve that section at all until we go  
through a huge reorganization process. I understand why...it's just  
tough to stomache. So...I guess I should go in and back out my changes?

>   Angela and CSL have invested time and resources in creating  
> scripts to automatically create patches from these pages.   We need  
> to know what impact changing the format is going to have on  
> generating those patches.

I agree with your statements...this is THE problem with having this  
both be admin help and documentation. There are areas where the two  
are fundamentally at odds.

> I think we should make improvements as you have suggested, but we  
> need to consider other improvements and make a plan for how these  
> will get implemented per the documentation coordinator's single  
> source vision for the module administration help pages.

Hmm. I don't think that sits only with the documentation coordinator,  
unfortunately, as all those nasty developers will have a say in how  
this gets done at a code level. I *think* there are some technology  
solutions/thinking need in this area which, as you say...we're going  
to need to think about and discuss.

--
Boris Mann
Vancouver 778-896-2747 San Francisco 415-367-3595
SKYPE borismann
http://www.bryght.com