Documentation & Books & related
alex at tweedly.net
Wed Jul 7 14:42:30 CDT 2004
At 08:23 07/07/2004 -0700, Richard Gaskin wrote:
>As with their paper-based counterparts, you may need to check out a few
>different entries before you find the one that answers your question most
>fully. But with more than twice as much documentation as included with
>Director, ToolBook, and other more expensive tools, the answer you're
>looking for is very likely covered sufficiently to get you moving forward
>so long as you're willing to invest almost as much effort as you would
>expect to employ with a paper-based index (the electronic version is
>arguably a bit easier since going to an entry is just one click as opposed
>to thumbing through pages).
>So maybe a useful question would be: How do we encourage folks to use the
>tools they have in hand now?
Make them easier to use (mostly talking about on-line documentation). It's
one click - if you don't mind losing your screen setup and context.
1. When one doc window (e.g. the Transcript dict) is open but buried under
other windows, clicking on Help/Search Doc does (or appears to do) nothing.
It should open a new window, or at least bring the current one to the
2. Follow proper OS conventions / guidelines. For Windows, in the
dictionary entry window:
- Page Up / Page Down currently don't work
- Up Arrow / Down Arrow do the wrong thing (scroll by page instead
of by small amount)
- Ctrl-F4 (or maybe Alt-F4) should close windows (this is the cause,
for me, of so often having a doc window buried where I can't see it ....)
- Ctrl-Tab (or maybe Alt-Tab) should cycle between windows (all of
them - not just the two main ones. Rev has open windows that I can't get to
without using a mouse - tsk tsk.)
etc. Lack of these means you need to use the mouse more than you
should need to - and that's not as easy as it should be, because the close
buttons, scroll-bars and scroll-arrows are smaller than standard ones.
When in the Transcript dictionary index window
- up-arrow / down arrow should move the highlighted entry, and return
should open its entry.
- left-arrow and right-arrow should move the text cursor within the
selection field at the top
(e.g. type in exolicitVariables - discover there is nothing showing
(because you typo-ed the "p" for an "o". Normal Windows conventions would
allow you to arrow back along the line and fix that letter - but instead
the left-arrow changes you to a different mode in the Help system.)
3. Provide a larger set of samples. The Recipes are good - but more of
them, and a few more which show complete (even if tiny) examples. Right
now, it's too easy to get a recipe which shows you the one line you need to
use - but doesn't help you with context.
(Sorry - I had a few specific examples in mind, but didn't get them written
down, and now can't go back to look again .... I think it was something
like rectangle where it told me to use something like set graphic to
rectangle - but didn't then either tell me, or give me any hyperlink to,
info on how to use that. OK, you can go back to the doc window and search
for graphic, and after reading that, go back to doc window and search for
create, and .... but one 10-line example would have told me what I needed
much sooner. I might have done better to make more use the "Back to
..." and "See also ..." boxes - but they're a pain to use - need to use a
mouse, and (I found) too low a success-rate to encourage using them. )
4. Provide an easy way to search through source code buried within stacks.
There are a good number of user-contributed stacks - they must contain lots
of useful examples of how to use features, commands, etc. - but there's no
easy way to find them. If this were a more traditional language / system,
I'd use find-files, or even find+grep to find the examples that use the
features I'm trying research - but there's no way to do that in Rev.
(Or maybe there is - but I don't know about it .... - so if there is a way
to do that, add it prominently to the docs).
5. Include a tutorial about how to develop some small feature *using* the
documentation. Something along the lines of
We have a set of folders, each named by a single letter. We want the
user to select a letter from a scrolling list of letters, and then display
a list of all the files within that folder - and the user can then select
one of those files and we'll display its contents in text area.
How do we do this ?
search doc for "files" ... this shows us ...
search doc for "folders" ...
i.e. find a case where there are a number of feasible words, and the first
one you think of isn't the one that is in the docs.
My perspective : I'm an experienced programmer - been building graphics
programs since mid-70s, used a significant number of different languages,
IDEs, systems. Most of my recent development work (for fun, not for
professional purposes) has been in Python - though earlier I did work in
I've just finished a trial license for Revolution - and decided that it's
not the right tool for me at the moment. The number of things that worked
and were easy and "brought a smile to my face" just wasn't quite big enough
to match the number of things that made me gnash my teeth in frustration.
Some of those I described above - and really they're issues with the IDE
rather than the documentation itself. There were also a number of
unpleasant surprises and things that I just found too hard to do.
(I'm typing this from memory - since my license has expired, I can't go
back in and cut/paste the actual code - so there may be something slightly
off in this example)
put "file:myfile.txt" into myVar
put URL myVar into myText
puts the contents of myfile.txt into the variable myText
put "myfile.txt" into myVar
put URL "file:"+myVar into myText
does something different (it puts the *name* of myfile.txt into myText)
That took me hours to figure out, partly because I was *sure* that sequence
to read the file was OK, and it wasn't producing any error - so I thought
the file had been read OK, and was trying to see why my processing of the
file was producing the wrong answer. Maybe it's just a bug, maybe it's
another example of the non-regularity of Revolution - I can't tell, and
couldn't tell from the documents. If there had been a more formal language
ref (BNF or similar ?) I might have figured out if it was supposed to work.
All in all, it just wasn't enough fun for me. I sent a longer, and probably
less calm and reasoned, version of this mail to Rev support, explaining why
I am not converting the trial license into a real one, and received a very
I hope that sometime (maybe ver 2.3) the balance will have shifted enough
so that the good things outnumber and outweigh the parts I found troublesome.
-------------- next part --------------
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.714 / Virus Database: 470 - Release Date: 02/07/2004
More information about the use-livecode