Another Area For Document Development

[Wilhelm Sanke]

On Mon, 7 Apr 2003, Dave Calkins <davecalk at surfbest.net> wrote:

> (snip)
> I did a search for "Tab Button" in the Document Search Engine, no such
> entry was found. This shows part of the basic problem. Why is a very
> common data selection method like this not even mentioned. A simple
> discussion about how to implement "Tab Buttons" should be addressed in
> the documents.


You should have searched for "tabbed button" (singular), this yields 18 
topics containing the searchstring. Using my "topsearch" plugin (see 
User Contributions), I find 14 hits on 12 cards of the Transcript 
Dictionary, 6 hits on 3 cards of stack "How To.." (revDocsHow), 2 hits 
on one card of the Glossary, indeed nothing in the Tutorials, and one 
hit in the Menu Reference.

> (snip)
> There are many broad topics that are common to most programs. How to
> implement them with RR should be something that is addressed in the
> documents. Using simple tutorials for the most common usages of program
> interfaces as well as for the most common types of programs RR is aimed
> at is a must. They should give step by step examples with screen shots,
> etc. for these most basic elements; elements RR can able to run circles
> around other programing tools.
> (snip)


The problem is - given the richness of the Metatalk/Transcript language 
- and the tremendous variety of applications you can create, that it is 
difficult to cover all "basic" problems in such "simple tutorials". They 
probably cannot even be treated exhaustively in publications like Dan 
Shafer´s book.
While only Metacard was around, I criticized its documentation on 
several occasions, because in quite a number of cases the entries served 
rather as "hints" or "reminders" instead of being very practical 
examples how to use language and syntax.
This changed with Revolution. I think the documentation is by far the 
best part of the new Revolution IDE, which I appreciate very much. You 
can see from my contributions to this and other lists that I criticize 
Revolution on a regular basis because the Rev IDE is in many cases not 
suited for the kind of stacks I happen to develop, because its speed 
problems and mutually interfering IDE elements.
I prefer to work with the Metacard IDE most of the time, but I very 
often use the Revolution documentation at the same time.

This does not mean that I would not agree with you on some of your 
proposals. The Revolution team have devoted a lot of effort to develop 
the documentation, add tutorials, make the docs searchable etc., and 
they are already heading in the direction of improvement you indicate, 
in so far they will most probably appreciate your critical 
recommendations, but this will take time. You have to take into account 
that Revolution is still in its early stages of development and has 
existed only for 10 months as an independent product since it acquired 
Metacard last year.

Maybe we will eventually see both  printed and included (as part of the 
IDE) versions of the Revolution documentation that come up to your 
expectations and will come free with the purchase of Revolution.

The old Toolbook documentation, which was a free part of the product, 
comprised two very thick volumes, the "Open Script Reference" and the 
"User Manual" along with more printed parts of the documentation, which 
were rather comprehensive and self-explanatory. The best documentation I 
can remember was that of "HyperPad", the first Hypercard clone for the 
now extinct DOS-world from Brightbill&Roberts, that came also free with 
the program. In the three years in which I used HyperPad alongside with 
Hypercard I think I have only directed questions at Brightbill&Roberts 
two or three times - as their documentation indeed covered all necessary 
aspects and included step-by-step practical examples for all parts of 
the PadTalk language and the HyperPad environment (but in retrospection 
it could well be that I did not yet have too many essential questions to 
ask back in 1990).

Regards,

Wilhelm Sanke