Documentation & Books & related

[Alex Tweedly]

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 
front, etc.

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
Problem description:
   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" ...
etc.
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 
Perl, and have done a fair amount of PHP and a little javascript.

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.
e.g.
(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 
nice reply.
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.

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