Updating documentation

[Sittampalam, Ganesh]

wren ng thornton wrote:
> On 11/8/10 5:41 AM, Johan Tibell wrote:
>> On Mon, Nov 8, 2010 at 12:36 PM, Sittampalam, Ganesh wrote:
>>> 
>>> That feels to me like a rule that would be better applied by the
>>> documentation tool, than by the individual writing the
>>> documentation. Especially as the syntax is more lightweight than in
>>> Java, it's so much easier to just automatically do it for
>>> everything than to stop and think each time.
>> 
>> In my experience, I don't think there's automatic way to decided
>> where to link or not. It's really a judgement call (and I sometimes
>> go back and remove or add hyperlinks). Sometimes I don't hyperlink an
>> identifier even the first time it's mentioned, for example because it
>> was hyperlinked in the introduction.
> 
> I believe the suggestion was not to add hyperlinks automatically, but
> rather to *remove* them automatically. For example, with such
> automation I can just write 'Int', 'Foo', or 'Local.Bar' everywhere
> and leave it up to Haddock to ensure properties like only the first
> one actually being a link.    

That was my suggestion, and I think Johan's objection is that it's not
possible to get the same results, because the inclusion or otherwise of
hyperlinks is also subject to a judgement call. His suggested overall
criterion is that links should only be used when the user is likely to
want to click on them, and he gives the (more mechanical) rules as
suggestions that might help documenters make that judgement.

Personally I think the gap in quality that can be achieved by using
human judgement rather than the mechanical rules is small, and in fact
users might rather have consistency. The other advantages you list also
weigh in favour of the automation.

Cheers,

Ganesh

=============================================================================== 
Please access the attached hyperlink for an important electronic communications disclaimer: 
http://www.credit-suisse.com/legal/en/disclaimer_email_ib.html 
===============================================================================