|
From: | Graham Percival |
Subject: | Re: GDP: chattiness in @seealso |
Date: | Thu, 15 Nov 2007 16:19:38 -0800 |
User-agent: | Thunderbird 2.0.0.6 (X11/20071022) |
Eyolf Østrem wrote:
On 14.11.2007 (16:18), Graham Percival wrote:I have a slight preference against #2 (sentences everywhere), since IMOI know you have, and you know this is the one I prefer. Giving a hint at WHY one should seealso ain't fluff. This isn't dungeons and dragons ("you are in a dark cave. To the east there is a link to Proportional notation, to the south is a snippet." etc).
I think you mean "this isn't zork", not D&D. :)
in most cases it's obvious why somebody might want to look at other section.... I'd say that in SOME cases it's obvious, but in many it's not, and if ageneral rule is needed, I'd go for 2 (with 3 as a variant).
Well, you're the one who'll have to go through and write sentences for every single @seealso section, so it's no skin off my back... what about the new Durations? (see tomorrow's GDP; should be online in about two hours. If you're not certain if you're seeing the updated ones or not: the updated one stick things in an itemized list)
At the very least, I want it clear which sentence refer to the Notation Reference, and which sentences refer to the other parts of the docs.
... I _really_ think this is completely unnecessary, though. And if you want to add full sentences to every single notation reference @ref{}, I assume you want to do the same for every @lsr{dir,snippet}, every @internalsref{}, etc ?
Mats, you're the yardstick for efficient NR use. What do you think of the compact vs. full sentence form of @seealso ? I don't want to approve any change that makes the NR harder to use for knowledgeable users, and IMO this is one such change.
Cheers, - Graham
[Prev in Thread] | Current Thread | [Next in Thread] |