Updating documentation

[Roman Leshchinskiy]

On 8 Nov 2010, at 11:56, Johan Tibell <johan.tibell at gmail.com> wrote:

> On Mon, Nov 8, 2010 at 12:57 PM, Roman Leshchinskiy <rl at cse.unsw.edu.au> wrote:
>> Why? I always try to hyperlink identifiers.
> 
> Hyperlinking something draws the users attention. Hyperlinking
> everything is almost the same as making e.g. every 5th word bold.

I would argue that documentation where every 5th word is an identifier is rather broken.

> You can use @id@ to make the identifier monospaced. It makes it clear
> that's it's an identifier without the visual weight of a link.

Personally, I don't find hyperlinked identifiers to add any weight compared to monospaced ones. If anything, they are easier to read for me.

> By first occurrence I mean first occurrence in some context. Perhaps
> the context is the documentation of a function. Use your judgement.

Yeah, well, my judgement is to hyperlink everything :-)

> You're right that documentation is often not read linearly. That
> applies to Javadoc as well and it's there they established this
> guideline.

I don't find their style especially enticing. In particular, they underline their hyperlinks which explains why they try to avoid them as much as possible.

Roman