Re: Updating documentation

On 8 Nov 2010, at 11:56, Johan Tibell wrote:

On Mon, Nov 8, 2010 at 12:57 PM, Roman Leshchinskiy 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