[documentation] Links to module pages from contributed modules

[Charlie Lowe]

Boris Mann wrote:
> 
> 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

There were a few where there was no configuration list. For example,

http://drupal.org/handbook/modules/legacy

If you see any with the contrib modules for which there is not a "You 
can" list where there are configuration options that should be there, 
definitely add them in.


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


Better than just a list of links would some information as to why these 
additional modules are useful with the module in question. That would 
make it worth having an additional page.

> 
> 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>".

What do you think, Kieran?

> 
> According to the guidelines (http://drupal.org/node/24566) -- there  is 
> nothing about "You can..." specified, and also nothing about  outgoing 
> links. 


It's there:

"The list of links should begin with the phrase "You can" and be 
followed by an unordered list of complete sentences that describe a task 
and identify the path to the page where administrators can accomplish 
that task. If the list has only one item it should be a single paragraph 
beginning with 'You can'."

Since you didn't catch it, maybe the explanation in that section needs 
to be better?


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

I checked. The format seems to be correct.