Documentation & Books & related

Wed Jul 7 15:54:54 EDT 2004

Alex Tweedly wrote (in frustration apparently):

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

I hope someone at Rev is listening in on this dialog.  The volume alone 
of comments (and the time people spent giving detailed suggestions and 
descriptions of problems), should be a clue to the level of frustration 
people are having with the dox.

That's not to say they aren't good, even comprehensive.  I didn't see 
that as the expressed complaint.  What I am seeing is the complaint 
that the dox in their current incarnation are not "accessible" (term 
used in a general way) to people trying to solve a particular problem.

And Alex isn't the only experienced programmer who has expressed the 
same frustration that relative newcomers have expressed.

I'd like especially to highlight one of Alex's suggestions:

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

Think of the things someone just starting out will need to know and 
give them to him in "words of one phoneme." It is very difficult for 
someone who "speaks the language" to remember what it was like when 
they couldn't.  This is true whether you are teaching medicine or 
teaching Rev.  And YES, you DO have to teach (Dan's comment about 
digging for pearls notwithstanding), cuz (deliberate bad spelling) if 
you don't,  you will continue to have people turning away in 
frustration.  Lost revenue, but, more importantly, lost user base. It's 
time to build critical mass guys and gals.

M

On Jul 7, 2004, at 3:42 PM, Alex Tweedly wrote:

> 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.
>
> ---
> 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
> use-revolution at lists.runrev.com
> http://lists.runrev.com/mailman/listinfo/use-revolution