Hi, I agree with many of your points, Steven.
> ... when I read > sample scripts, they are uncommented and I just can't seem to figure out > what they are doing, or why they must use the functions they use to do the > things they are doing. I see this all the time. Very often in Rebol programs, it's just about impossible to figure out what's supposed to be going on. Only a small percentage of the hundreds of programs in the Rebol library are documented. In my experience, there's no such thing as a self-documenting programming language. Documentation must be written by the developer; it's part of the job, like it or not. Perhaps Rebol needs it's own built-in documentation standard. MakeDoc is a very good tool for that purpose, but I don't see it being used very much. An embedded documentation feature, a bit like Perl's POD (Plain Old Documentation) or Java's JavaDoc, both of which are embedded within a source program's comments, might be a nice thing to add to Rebol. The embedded docs could be generated by running the source files through some kind of a MakeDoc front-end. This way, the program and the source code are always together, which should encourage keeping them both up to date and in synch. > I probably shouldn't say this since I have not read the VIEW documentation > for a while, but I have read it, a couple times, and I was a bit lost in > all the "faces" and "facets" and "feels" and so on. I will accept this as > my fault; probably I just have to read it again. But a nice, thick, > complete VIEW manual would be nice. No Steven, it's not your fault. I too am "a bit lost in all the 'faces' and 'facets' and 'feels'" We shouldn't have to dig through a half dozen or so scattered and out of date documents in order to try to figure out how a major feature like View is to be used. I tried Rebol several years ago, and I didn't "stick" because trying to figure things out from the always skimpy and out of date docs was simply making me exhausted. While I was gone though, I did keep an eye on Rebol, and several months before View 1.3 was released, I noticed that the Rebol Dictionary and User's Guide had been dramatically improved, so I decided to give it another try. But I soon discovered that the View docs still hadn't been consolidated, expanded or updated in those four intervening years. Now that View 1.3 has been released, it's even more critical that its documentation be brought up to date, but that's not even a low RT priority, it's not even mentioned in RT's future plans (see http://www.rebol.net/article/0181.html). I've given Rebol a fair chance twice now. Most people would only do it once, if at all. But if I have to keep wearing myself out trying to get by with inadequate documentation, I won't be able to "stick" around this time either. I don't think that it's reasonable for RT to keep adding major new features without pausing once in a while to get (and keep) the docs up to date. Most programmers wouldn't be as patient with the docs as I've been, and this could be a big reason for the low "stick" factor. I'm again trying very hard to stick because I truly believe that Rebol could represent a programming revolution by simplifying nearly every aspect of the art. But it's a mistake to believe that just because something is simplified, that it's necessarily easy. In fact, simplification can sometimes, make understanding harder, at least for a while, because each language element incorporates so much power. Rebol is not easy to pick up, if only because it's so "strange" and powerful.The lack of documentation only makes things worse. Rebol is strange in a very good way, because it's that very strangeness that gives Rebol it's power. I have a great respect and appreciation for Rebol's brilliant design and impressive potential, but I need to start getting productive with it soon, and for that to happen, I need to have good documentation soon. Please don't blame yourself, Steven. I'm not going to blame myself either. I've successfully learned and become very productive with dozens of programming languages in my forty years as a computer professional, and I know a little bit about what it takes to get off the ground with a new language. It takes a lot of hard work, and it takes a lot of good documentation. Just look at what programmers of Perl, Rexx, and Python (languages which I've learned from their docs), have available in the way of beginner, intermediate, and advanced documentation, and compare it to what's available for Rebol. Rebol has been around long enough, that this situation should have been corrected by now. I'm not really trying to slam Rebol or RT here. I have tremendous admiration and respect for both. I'm just very concerned that the current state of its docs will be one of the reasons for Rebol's downfall, and I'd be really sad to see that happen. Best regards, Bernie Schneider The individual has always had to struggle to keep from being overwhelmed by the tribe. To be your own man is a hard business. If you try it, you will be lonely often and sometimes frightened. But no price is too high to pay for the privilege of owning yourself. -- Friedrich Nietzsche -- ----- Original Message ----- From: "Steven White" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Tuesday, July 12, 2005 1:28 PM Subject: [REBOL] Re: REBOL Tutorials > > I can offer a few observations on the "stickiness" issue since I have = > come, but not stuck. (I have stuck a bit, because I have some simple = > REBOL scripts in production on an RS6000 where I work, but I have not = > stuck as much as I would like to.) > > When I first came, I was used to languages with reserved words, so I was = > looking for that in REBOL as some "firm ground" to stand on while I looked = > around. I found the sample scripts VERY hard to understand since there = > was no punctuation, everything was in lower case, and all the words were = > generic things like "file" and "data" so I couldn't figure out what was = > going on. I finally got around that by usiing upper case hyphenated words = > for the words I made up, and lower case for all the REBOL words and = > functions. That problem now is in the past, but it was quite a big one = > for a while. > > The next issue for me probably is my fault for not paying my "dues," that = > is, beating my head against the wall for long enough, but when I read = > sample scripts, they are uncommented and I just can't seem to figure out = > what they are doing, or why they must use the functions they use to do the = > things they are doing. I would like to see some samples that are HEAVILY = > annotated, to the point where there are more comments than code. I could = > provide some examples, since I have had to do that for myself so that when = > I go back to scripts I have written I myself know what I was doing. > > I probably shouldn't say this since I have not read the VIEW documentation = > for a while, but I have read it, a couple times, and I was a bit lost in = > all the "faces" and "facets" and "feels" and so on. I will accept this as = > my fault; probably I just have to read it again. But a nice, thick, = > complete VIEW manual would be nice. > > Maybe the motto should be something like, "simple things should be simple, = > and complicated things should be possible, if only you can figure out how = > to do them." I can't quite explain it, but I have observed it an probably = > could construct an example. On thing that pops to mind is the slider. Of = > course I know how to put a slider on a screen, it's as simple as can be. = > But once it's there, I don't know what to do to make it slide, and make = > things slide with it, and so on. > > I think this probably all boils down to documentation. Maybe someone = > should go through every word in the dictionary and write up some detailed = > explanations and examples. Actually, I would be happy to do it myself, = > but of course there is that chicken and egg problem--how can I explain it = > without understanding it. > > Now that the Microsoft antitrust settlement is in place and Microsoft = > theoretically can't bully computer makers, would it be possible to get = > REBOL pre-installed on all new computers? Just the free version, of = > course. I have thought of some script ideas to give to people I know, but = > if I do that I have to tell them how to obtain REBOL first. I think it = > would be nice to have REBOL pre-installed on all Windows computers and in = > all Linux distrubutions. I know it is "easy" to download and install = > REBOL, but I have done it a number of times and there still is something = > confusing about it (I have commented on that to the REBOL feedback). > > This final item probably is not relevant because any language has its own = > strengths. If there is something one wants to do and it can't be done = > easily in REBOL, the answer probably is to find a language where it CAN be = > done. One does not fiddle bits in COBOL, for example, although it can ge = > done with effort. It seems that REBOL is not designed for "data processing= > " kinds of operations, but a lot of what people do with computers is data = > processing in some form. The example in my mind is files. In my world, = > files are composed of records, like the employee record of a payroll file. = > It seems that REBOL is not designed for that. One reads a whole file = > into memory, perhaps as a big block, and writes it back all at once. This = > idea showed up in the first REBOL book, the Official Guide, I believe, = > where one logical file in the video store data base was actually broken up = > into several physical files just because there was not a way in REBOL to = > read one "record" of a "file." I wonder if that might be a deficiency of = > REBOL worth investigating. > > I have not given up on REBOL. I am trying to think of some application at = > work, where we have 400 desktop computers, that is so cool everyone wants = > it, and that would require loading REBOL on all our computers. No luck = > yet. > > > Steven White > City of Bloomington > 1800 W Old Shakopee Rd > Bloomington MN 55431-3096 > USA > 952-563-4882 (voice) > 952-563-4672 (fax) > [EMAIL PROTECTED] > > >>> [EMAIL PROTECTED] 07/07/05 10:21 AM >>> > Prompted by my last comment, I just wanted to add something... > > I agree that REBOL tutorials are very important to "visitors" who > are checking out the language for the first time. > > The way I view it is: if the userbase is not constantly growing > then there is something wrong with the approach or wrong with the > product (language). > > This is sometimes called "stickyness". People come visit the site, > check out a few pages, but then... do they stick? Do they download > it? Do they give it a fair chance? > > I think it is very important. But, I also think that we have a long > way to go to improve our intro examples and tutorials. That was one > of the main reasons I created the cookbook a few years ago. But, > actually the cookbook is not enough. > > I know a lot of people who use REBOL and love it. But, I also know > too many people who have tried it and not "stuck". I wish I knew > more about why... and also what we could do to improve the stick > factor. > > So, what do you think is the #1 thing we can do to get greater > stickyness? I estimate we get more than 15,000 visitors checking > out "newbie" pages each month. How can we get more of them learning > and using REBOL? > > -Carl Sassenrath > REBOL Technologies > --=20 > To unsubscribe from the list, just send an email to=20 > lists at rebol.com with unsubscribe as the subject. > > -- > To unsubscribe from the list, just send an email to > lists at rebol.com with unsubscribe as the subject. > > > > -- > No virus found in this incoming message. > Checked by AVG Anti-Virus. > Version: 7.0.323 / Virus Database: 267.8.13/47 - Release Date: 7/12/2005 > > -- No virus found in this outgoing message. Checked by AVG Anti-Virus. Version: 7.0.323 / Virus Database: 267.8.13/47 - Release Date: 7/12/2005 -- To unsubscribe from the list, just send an email to lists at rebol.com with unsubscribe as the subject.
