Another Area For Document Development

[Dave Calkins]

> Subject: Re: Another Area For Document Development
>
> FWIW, this is one of the areas I'm trying to tackle in my project.  The
> solution I'm considering currently (which is geared strictly towards
> nonprogrammers) is to provide sample stacks with sample scripted 
> goodies
> (ala Hypercard's 'Sample buttons' & 'Sample fields' stacks).  I'm 
> leaning
> towards this method for the following reasons:
>
> 1.  People hate reading manuals/documentation (it can be confusing and
> frustrating for the very reasons you outlined...
> 2.  The documentation isn't visual, so even providing a cookbook script
> doesn't tell you how to go about implementing it in a meaningful way
> (especially if you are a nonprogrammer).
> 3.  Sample stacks put the items in both a visual and  contextual frame 
> of
> reference.  People can look at the item, look at the script, and 
> observe
> the output without having to look at a page of code and then try
> copy-pasting or typing things in and hoping one got everything together
> where it was supposed to be).
>
> 4.  Sample stacks provide for code reuse and modification -...

> Thoughts?
>
> Judy


Hi Judy,
Sounds like a great addition. Again it is aimed at the new programer. 
(We were all new at one time. Actually we usually are new quite a few 
times, because RR is rarely the first language a person has used. The 
learning process just comes faster if we have been through the process 
a few times.)

>
> Maybe there are few sample stacks because are just less interesting to
> make.  If RevNet is any index of this, note that the Tutorials category
> in the Stacks section is by far the most sparsely populated.
>

True, the advanced programer will need tutorials a lot less, but even 
we benefit from them, it just less time for us to go through them.

> In contrast, there are a lot of libraries and tools available through
> RevNet.
>

Yes, but many newbies go "what's a library?" Searching the docs in 2.2 
reveals 398 matches. He has to get down to #202 before he finds out 
what a library is. He does this by following the description Under the 
Heading "How to create a library":

A library is a set of custom commands and custom functions for a 
specific application or a specific area of functionality. For example, 
if you’re writing an image-transformation application, you might want 
to collect your transformation handlers in one place, where you can 
easily use any of them from any script in your application.

To create a code library, place the handlers you want to re-use in any 
object that’s available in your stack, then use the insert script 
command to add that object to the message path, as in the following 
example:

   insert script of group "MyLib" into back

Handlers in that object’s script are now accessible to any other 
handler in Revolution.

> -- 
>   Richard Gaskin
>   Fourth World Media Corporation
>   _



> Right, but, again, I'd guess that most folks perusing RevNet aren't 
> total
> programming newbies.
>

Yep, that's the point.

> I don't find example stacks boring to make... but I'd probably find
> documentation not fun... still, the fun factor or lack thereof isn't
> necessarily an indicator of importance, is it?
>
Nope, but the "fun" that new people have in trying to work through 
these issues without a guide is an indicator of it's importance.
> David with his tabs question -- if there were a buttons example stack 
> that
> he could have taken apart, perhaps he wouldn't have needed 5 or so 
> emails to the group...  Not that the number is significant, but an 
> absolute
> novice probably would have just given up in frustration and gone back 
> to
> PowerPoint after the first two...
>
> Judy

People learn by example. Seeing an example of it , reading about it, 
taking it apart, seeing how it compares with what I want it to do. The 
examples don't have to be full featured programs, but they do need to 
be starting places which will get people going on the right track.

Dave Calkins