AltME: Red Docs

Messages

Gregg
Do you mean like a standard library reference Peter? I have notes for something like a Nutshell series book.
PeterWood
What I'm thinking of is a short explanation of each value! type.
Something like this:
A char! value represents a Unicode code point. It is a number in the range hexadecimal 00 to hexadecimal 10FFFFF.
The literal value of a char! value is of the form #"a" or #"^(0032)".
Gregg
I would call that a "reference", and could be an appendix in the core user manual.
DocKimbel
Listing all the datatypes should be part of 1).
Gregg
Yes. Working on some of that now.
DocKimbel
By the way, a preliminary work would also be to define a lexicon for the basic concepts, like talking about "variables" or not, "assigning a value to a word" vs "giving a meaning to a word in a context". We need to define a common vocabulary so that the docs look consistent regardless of who is writing.
Gregg
Yes. That will be very important.
DocKimbel
I am also wondering if a single entry point for (1) is the best option. We know from Rebol that the learning curve has at least two steps (Carl's lake analogy) the surface and the depth. The surface is very quick and simple to learn, but might be misleading or even confusing for users with a CS background. So, there's a second "advanced" step in the learning process where you usually get the "eureka" moments, once you get things like code/data duality or the nature of definitional and dynamic binding.
Gregg
I'm sure we'll want special docs for advanced users who would otherwise not find the information sprinkled in the standard user guide.
DocKimbel
So for (1), you suggest we aim at the "surface" only?
Gregg
I think (1) can, and should mention these things, but doesn't need them as complete chapters. They could be advanced chapters or appendices. But could stand alone as well.
Pekr
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 ...
DocKimbel
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.
DocKimbel
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:
http://en.wikibooks.org/wiki/REBOL_Programming/Design_Guide
Andreas
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.
Gregg
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.

PeterWood
Andreas: Yes. The definition of values should be in the language reference.
PeterWood
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.
DocKimbel
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.

Last message posted 404 weeks ago.