On Monday, April 5, 2004, at 10:06 AM, [EMAIL PROTECTED] 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
_______________________________________________ use-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/use-revolution
