AltME: Red Docs


Wasn't there once the community effort, to bring some kind of better docs to Rebol? I remember we defined structure or something like that ...
Having a look at it. It's a patchwork of docs written in different styles, mixed up content, bad examples and inaccuracies...not really usable.
Some parts of the Rebol user manual were put on that wiki (simply copy/pasted), and all that wiki content is Creative Commons license. :-)
Like some of these parts:
Peter: that "value" explantion is precisely one part of what I'd put into a language reference ("(4)").
Listing of all the datatypes should of course also be a part of the user's guide ("(1)"), but on a different level. User guide is exemplary, a quick overview. The language reference should be comprehensive.
In general, I like Rebol's user guide quite a bit. What I don't like about it -- and I don't think the "user's guide" really is the place to put it -- is that it is very skimpy on almost all topics touched. It doesn't discuss the deeper technical details, the corner cases, etc.
A quick-start guide will be good, and should be material we can extract from the official/user's guide. Or should at least be easier to write once we've done that.

Andreas: Yes. The definition of values should be in the language reference.
Perhaps I can summarise and make a short proposal:
1. We want to have good quality documentation ready for the launch of Red 1.0. (By good quality, I mean that, first and foremost , the content is accurate. Second come style and presentation.)
2. We see the need for:
    a. user manual
             b. dictionary of words
             c. tutorials
             d. language reference
             e. quick start guide
3. I believe that the early adopters of Red 1.0 will be either people currently using Rebol or experienced developers. The inexperienced will follow some time later.
So my proposal is to focus on the following three documents that experienced Rebollers/Developers would look for:
    i) Language Reference
    ii) Dictionay of Words
    iii) Quick Start Guide.
Actually, I would like to have the docs (at least (1)) for the first "public alpha", so around end of March (as soon as we have good enough GUI and I/O). We'll start doing promotion/buzzing, so we need it before 1.0.
Peter, Language Reference will be very technical, not practical. It won't explain you how to use Red, but describe Red's syntax (using BNF), semantic rules, notes about implementation and exhaustive list of core functions.
Peter, I am hoping to attract many beginners/inexperienced users for 1.0 (or even before), and not only experienced ones. But it's difficult to predict in which category of users Red will generate the most traction.
So the User Guide should be the priority.
I think so.
Doc, I hope to focus on the beginners and young users myself. I taught high school science for six years and I never lost my interest in promoting programming as a tool for my students that were not necessarily interested in computers...Now wiith Red I hope to show the FUN in using computers to create things (apps/projects). My children are ages 8 and 9 and I will be using them as a test case for a book/website/curriculum that I am going to pursue.
Alan, glad to hear that. I would love Red to be used for education. We would probably need to build some additional layers in provide simpler interfaces for young beginners. I think you should talk with PeterWood more. ;-)
For all of us who want to use Red to teach, we should look at old Logo resources. There are a lot of beginner and turtle graphics examples out there, but there's also NetLogo and Brian Harvey's amazing series "Computer Science Logo Style", though that's more advanced. I even did a tiny turtle graphics interpreter in REBOL a long time ago.
Some tools and dialects are all we need. ;-)

What has been the best resources out there for REBOL in terms of education?
Learning what to do, and not do probably has value, but copying work that has already been done could save a lot of time and energy.
> What has been the best resources out there for REBOL in terms of education?
The old mailing list ...
Andreas +1. On docs, Carl said he didn't want the REBOL user guide copied. Nick's work, and some others', are also great resources. I hope we can leverage those in the future. The main thing there will be differences in Red that have to be accounted for. A LOT of REBOL docs will apply to Red directly as well, which is great.
And, yes, if you're thinking it would be good to document the differences as well as compatibilities between REBOL-like languages, I started some things on that a long time ago. A lot of our work now can be looking in dark corners and dusting things off. Bulk prose (the content) is the big stuff now.

Last message posted 65 weeks ago.