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.
--- 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
_______________________________________________ use-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/use-revolution
