Completeness of Revo Docs (was Re: path of a 'closeStackRequest')

[Richard Gaskin]

Graham Samuel wrote:

> On Thu, 16 Jan 2003  Richard Gaskin <ambassador at fourthworld.com>
> 14:09:53 -0800 wrote:
>> Graham Samuel wrote:
>> [..]
>>> send "someMessage" to "somewhere" in 5 seconds
>>> 
>>> weren't covered in the Dictionary;
>> 
>> I wonder if the problem may be a version mismatch.
>> 
>> In v1.1.1, the second example in the Transcript Dictionary entry for the
>> send command shows the use of a timer to send a message in a given number of
>> seconds , and the timer option is also shown in the syntax listing above the
>> examples.
>> 
>> What version are you using?
> 
> I'm using 1.1.1, but you've just proved my point about having to read
> around the subject. If you look up 'seconds' in the Transcript
> dictionary, you only get one usage (the function which returns the
> time in seconds). If you didn't know about 'send', you wouldn't find
> it there.
> 
> It doesn't mention the other usage even in the 'see also' listing,
> nor that the singular 'second' is also recognised in some contexts
> (this appears in fact, but under the backgroundColor property - and
> that entry doesn't  mention the usage 'get the second item of
> myContainer'...). So to know Transcript in full, you do have to read
> a lot of stuff simply in a spirit of enquiry, which was my point.

Good feedback.  When I was working with Christopher Watson and Ken Ray on
the SuperCard docs, one of the toughest tasks we had was making the index.
It's hard to guess the perspective of the new user and how they will
approach looking for a particular topic.

Small world as it is, it was Jeanne's great tome, "HyperCard 2.2: The Book",
that Christopher insisted we use as a guide for structure and completeness.

But even our best efforts at the index -- huge leap forward as they were,
resulting in the second most comprehensive set of printed manuals to
accompany an xTalk* (can't really get first place up against Seybold's 20+
volumes for Gain Momentum) -- still had holes in it that didn't fully mesh
with the user's initial understanding of where they might look for a
particular topic.  We caught a large majority of queries, but still missed a
few, and we had to be mindful of page count so there was only so much we
could do.

After I got my printed copies of the SC 2.5 docs I laid the Language Guide
on my desk next to a stack of Director manuals -- the stack of all Director
5.0 manuals together was shorter than the SuperCard Language Guide alone. :)
FWIW, if printed in a similar format the Rev language guide would be at
least 20-30% larger than the one we did for SuperCard.

One of the nice thing about Rev's online docs is that they can be enhanced
with each release, without the stack of slender addendums that supercede the
main volumes (not to mention staggering printing costs, which is why I
suppose so many of even the big companies like Adobe and Macromedia
under-document their wares).

-- 
 Richard Gaskin 
 Fourth World Media Corporation
 Developer of WebMerge 2.1: Publish any database on any site
 ___________________________________________________________
 Ambassador at FourthWorld.com       http://www.FourthWorld.com
 Tel: 323-225-3717                       AIM: FourthWorldInc