use-revolution Digest, Vol 7, Issue 23

[Dave Calkins]

On Monday, April 5, 2004, at 10:06  AM, 
use-revolution-request at lists.runrev.com wrote:

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

Actually I did search under "tabbed button" and the information you 
mention is what I referred to as the "simple one card definitions". 
"How to disable a tab in a tabbed button" etc. I entered the "Tab 
button" (a common name that should be found by the search engine) and 
used that as an example because that is the same mistake that we have 
seen time and time again over the past two years. I should have 
mentioned it in my post when I wrote it, but I was writing it at 2:00 
in the morning. As one examines the information found on a search for 
"Tabbed Button" my point becomes very clear. The only information 
listed are the individual elements that makes up the controls needed to 
use a tabbed button. There is no post that one can go to that actually 
shows you how to integrate and use the elements in an application. Even 
having a reference to a cookbook that shows you how it looks and works 
would greatly reduce the number of questions. It won't eliminate all 
questions, but then the responses are easy. "Take a look in the 
cookbook to see how it works."

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


Elements of that are true, the Metatalk/Transcript language are vast. I 
will disagree with the implied thought that because the language is 
vast, the documentation  can't or shouldn't cover certain basics. My 
statement didn't suggest that the docs address "all" the basic problems 
that can come up because of this vastness of the language. Your 
statements partially make the point that my post was trying to address. 
Take a look at the most common themes of questions asked over the past 
two years. They most often fall into several categories. Developing and 
working with a database, using arrays,  developing simple web 
management / browser features, using images....


> They probably cannot even be treated exhaustively in publications like 
> Dan
> Shafer´s book.

That is also why I stated that the docs emphasis should not be (and is 
not) aimed at advanced programing levels. They should touch upon the 
basics though.


>
> This changed with Revolution. I think the documentation is by far the
> best part of the new Revolution IDE, which I appreciate very much.

I agree that the documentation provides a great deal of information. 
They are much better in the volume or amount of information that they 
cover than most other platforms. My point was that there are only four 
actual topics found the tutorials. We occasionally see questions 
dealing with property profiles, but the lack of questions in these 
areas indicate that when you have tutorials, even ones that don't have 
a visual reference, they seem to work. Most of the cookbook section 
does not address any of these common programing concerns either.

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

Actually the categories found in the tutorials have not changed in two 
years. The getting started section, Menu builded, animation builder, 
geometry management, property profiles, and an independent study were 
found way back then. Where is a tutorial showing how to use the various 
features the "Application Builder?", etc. (by the way in 2.2 
"Application Builder" returns only one reference to the AP and it is 
just a statement in the "Rev for experienced programers" section 
stating that the "Application Builder exists. Just another example of 
the glaring need.


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

Agreed, the ability to search the docs was a vast improvement. Kevin's 
reassurances about correcting the visual and kinesthetic aspects of the 
docs are very positive, and yes these things will take some time.

I think they could speed things ups in many ways.

They could utilize people on this list and the improve-rev list. There 
are many who could create a simple tutorials or cookbook additions that 
could be included in the docs.
These could be and I think should be sought out by the rev team. If the 
rev resources are stretched to tight. These people could be rewarded 
for their contributions with rev licenses, resource help for their 
projects, what-ever.

There are a number of folks who are attempting to make up for some of 
these deficiencies by creating web site references and resources that 
others can use to help them learn some of these things. Thats great. It 
is slightly self serving in that the more people that learn and use rev 
the longer and more productive the rev engine can become. For the most 
part I think that these actually tend to be a labor of love.

They are an outside resource, but the can't actually make the documents 
better unless their work is incorporated into the documents themselves.

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

I will disagree here. The fact that Metacard has been brought in house 
has not actually changed Rev much in this area. Yes, it has given Rev 
more security and control over the engine which is forward looking and 
long term in scope, but the actual changes are with regard to the 
documentation have been because of this minimal. Rev has been in 
development for several years. This is an on going aspect of programing 
languages. They either continue to grow and develop, meeting the needs 
of their programers, or they die a slow and painful death. I believe 
that RR has what it takes to grow, develop, and take market share from 
other languages.

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

That would be nice but I'm not going to hold my breath.
>

> Regards,
>
> Wilhelm Sanke
>
>

I know the the improve-rev list is specifically geared toward the 
professional programer and is where you are supposed to post 
suggestions for improving rev. I have posted the to that list as well.

Because this list is where most new users are, why not use this list to 
develop the tutorial categories that folks think should be added.

Dave Calkins