Another Area For Document Development
sanke at hrz.uni-kassel.de
Mon Apr 5 12:00:40 CDT 2004
On Mon, 7 Apr 2003, Dave Calkins <davecalk at surfbest.net> wrote:
> 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.
> 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.
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
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).
More information about the use-livecode