[documentation] Links to module pages from contributed modules

[Boris Mann]

On 15-Jan-06, at 10:46 PM, Charlie Lowe wrote:

> Boris Mann wrote:
>>> 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?
>
> I made a suggestion in this thread for how we might accomplish  
> linking to the project page using the current format. Related  
> modules could certainly go on a subpage. We could discuss these  
> possibilities.

Yes, I saw that...I didn't realize the "You can also..." was part of  
the format, since I didn't see it everywhere. I will fix. Basically,  
it's an extra section where you can put links etc. that shouldn't/ 
won't screw up the format? Great -- FOAF is an example: http:// 
drupal.org/handbook/modules/foaf

I don't think related modules should go on a sub-page. It should if  
it were longer, but it's a handful of links. I think I'll take this  
out, because this is one of those areas where it's really really good  
to have for online documentation...but extraneous/bad for admin/help.  
As someone else mentioned somewhere along the way, matching this  
directly on the project page is probably a good place for this as we  
turn on categorization for projects. And in fact, the link to the  
project page will then allow people to discover that info from there.

OK...so to condense that rambling: I propose that the guidelines be  
amended to include the last link in the "You can..." section of the  
form "visit the <a href="http://drupal.org/project/zzz">zzz module  
project page</a>".

>> 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.
>
> Is there a sudden interest in developing a better technological  
> solution? That would be great. The issue was raised last spring/ 
> summer, and no one had one to offer that would be accepted by Dries  
> and meet the needs of translators.

Yep, I know...that's what I was thinking of. And we need to do more  
of to solve nicely :P

> In the meantime, Kieran and CSL have easily invested much more time  
> developing the admin/help documentation in the last six months than  
> everyone else in Drupal combined (and more time than probably  
> everyone spent in the previous couple of years). They have been the  
> de facto admin/help maintainers. Much like you would with a module  
> maintainer, why not seek documentation solutions that assist them  
> in what they have been doing?

I have nothing but praise, and of course we want to assist further  
efforts. I guess I just now have my head wrapped around the two  
sometimes-incompatible needs -- good online documentation/handbook  
vs. good admin/help.

According to the guidelines (http://drupal.org/node/24566) -- there  
is nothing about "You can..." specified, and also nothing about  
outgoing links. Of course, adding the link to the project page could  
also be automated. Can someone please review the changes to FOAF to  
see if this is OK? http://drupal.org/handbook/modules/foaf -- I  
believe I created the proper auto-doc links....

(a bit later...did the same for audio module, a review would be  
appreciated....I'll work my way through contrib doing more auto-doc  
changes)

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