Updating documentation

[Johan Tibell]

Hi Roman,

On Mon, Nov 8, 2010 at 2:30 PM, Roman Leshchinskiy <rl at cse.unsw.edu.au> wrote:
> I would argue that documentation where every 5th word is an identifier is rather broken.

But it's not that uncommon in Haskell documentation, the main reason
is probably that since the parameter names don't appear in the
documentation, people refer to the arguments by type. For an example
of excessive hyperlinking see:

  http://hackage.haskell.org/packages/archive/bytestring/0.9.1.7/doc/html/Data-ByteString.html#v:intersperse

"O(n) The 'intercalate' function takes a 'ByteString' and a list of
'ByteString's and concatenates the list after interspersing the first
argument between each element of the list."

- The documentation links to it's own definition
- The documentation links to ByteString twice. In fact, the whole
library links to the ByteString hundreds of times, even though people
are highly unlikely to click on these links.


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

We can change the style of the @id@ markup, it's orthogonal to the
hyperlinking issue. I personally like the style use in

  http://code.google.com/appengine/docs/python/datastore/modelclass.html

where identifier are monospace but appear in a color that makes them
stand out a little bit more.

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

Although that's not the rationale they give for not doing so.

Johan