License Prices, Real, and docs

[Jeanne A. E. DeVoto]

At 10:15 PM -0700 6/6/2002, Troy Rollins wrote:
>1) we need a scripting cookbook. Preferably printed, and we have no
>problem with the concept of paying for it (like the manuals.)

Next version. It is being worked on even as I type (well, ten seconds
before I started typing, and probably ten seconds after I finish, anyway).

>2) in the Rev on-line docs - all links should have color or some
>indication of being "hot". It is EXTREMELY poor design to have hot text
>which is based on invisible hotspots.

Sorry, but no. Let me explain.

The hot spots on a web page (to take one example) are generally primary:
that is, they are gateways to information that all readers are presumably
interested in. Given this, the visual measles that afflicts most web pages
is a reasonable price to pay; it makes the page less readable, but it helps
you find the links.

The clickable hot spots in Revolution's documentation are of two kinds:
Transcript terms and glossary entries. The Transcript terms are primary,
and they're marked with boldface - which compromises readability somewhat,
but 1) makes them easy to find and 2) prevents problems where a Transcript
term is also an English word, and therefore might cause confusion if it
weren't marked in some way. (E.g. references to the "it" variable:
"Therefore, if you need to use the value of it, make sure none of these
commands is executed between the time you set it and the time you read its
value.") Failing to mark a primary hotspot is indeed bad design, because
the assumption is that all users are interested in this further
information, and not marking it is making the user hunt for it.

Glossary entries, on the other hand, are not primary sources of
information; they're not going to be useful, generally speaking, unless the
term defined is one you don't know. If you don't understand a word,
clicking it to see whether a definition is available is a fairly natural
thing to do, whether the word is marked or not. But clicking the glossary
entry for a term you already know is a waste of time, and not something the
user should be invited or prompted to do.

Marking the glossary entries also makes the documentation very difficult to
read because it introduces so much visual distraction. I keep the
underlineLinks turned on when I'm editing, so I can see what I'm doing, and
I can tell you it's not a pretty sight and not easy to read for sense. It's
too much harm to both readability and usability for too little gain, in
this case.

--
Jeanne A. E. DeVoto ~ jeanne at runrev.com
Runtime Revolution Limited - The Solution for Software Development
http://www.runrev.com/