(Original reply seems to have not made it to the ML, so here's
another try)
Hi Gregg,
You've made some good suggestions here...
> Something we need is a way for people to tell RT "what's
hard", kind
> of like the "wanted" list the cookbook has. Unfortunately, I
think the
> cookbook has entries for a lot of those requests, but they
haven't
> been marked as done.
I hadn't been aware of the cookbook, but I just took a look at
it, and it's great. I've already learned a lot just from a quick
perusal. It seems like a very good asset.
> ... I don't think our problems today fall into two
> categories: 1) the docs don't exist 2) it exists, but we can't
find
> it. I think #2 is the much bigger issue. If so, the problem we
> *really* need to solve is the organization and search
capability.
As one who previously abandoned Rebol several years ago because
of documentation issues, let me say some good things about the
current state of the docs. I came back to Rebol mainly because
the docs are so much better now than they were on my first time
around. The organization of the dictionary is wonderful. I can
nearly always find things quickly and easily. The user's manual
is equally well organized, and the content, while still of
variable quality, is far superior than it was earlier. Since
these are the two most important documents for me, I'm certainly
encouraged by the improvements.
In general, what's there is quite good. It's what's not there
that's giving me fits at the moment, and with the release of
Core/2.6 and View/1.3, it's suddenly become an even bigger
issue.
I think that what's now in the dictionary and user's manual
represents a solid base upon which to build. It seems to me that
the most glaring omission is the documentation for Rebol/View.
Properly documented, Rebol/View could be the simplest and
easiest GUI development technology ever. Even other so-called
"easy" tools, Tcl/Tk, Java/Swing, Visual Basic, etc., require
way too much time, effort, and debugging just to get a GUI
going. After all, a GUI is only a front end to an application,
isn't the application. Programmers should be able to put the
bulk of their creative efforts into the development of the
application, not the GUI, which is really just a device to make
it easier and more pleasant for the users to operate the
application. I think that Rebol/View and VID have the potential
to do for GUI's what SQL and DBMS's have done for data
management, once we have better docs.
If VID is so easy to use, and is truly cross-platform, then why
aren't programmers flocking to Rebol just for this feature? It
sure looks like the holy grail of GUI development. Perhaps many
do actually take a look at it, but just don't get it quickly
enough because the docs aren't yet ready, so they go back to
doing things the difficult but familiar way. I know that I find
the existing View docs to be too scattered, fragmented and
confusing for me to feel very confident that I truly know how to
use it well.
As you pointed out, searching for things in the documentation is
also a problem, with the exception of the dictionary. While we
still need more, there really is a lot of documentation already,
but much of it is scattered and unindexed. Just today, I've been
unsuccessful in locating something I need to recall about a
Rebol feature. I know that it's documented because I saw it
recently. Now I can't locate it again, and it's really holding
up my progress on a program I'm writing.
Bernie Schneider / [EMAIL PROTECTED]
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: "Gregg Irwin" <[EMAIL PROTECTED]>
To: "Bernie Schneider" <[EMAIL PROTECTED]>
Sent: Wednesday, July 13, 2005 4:38 PM
Subject: [REBOL] [docs] What's hard? (was: REBOL Tutorials)
>
> If I can use a quote from Bernie as a lead in...
>
> "What's troubling me now, is the amount of time it takes me to
get
> stuff to work due to the difficulty of finding things in the
docs."
>
> Something we need is a way for people to tell RT "what's
hard", kind
> of like the "wanted" list the cookbook has. Unfortunately, I
think the
> cookbook has entries for a lot of those requests, but they
haven't
> been marked as done. Also, a lot of them are things that come
up
> periodically, so the answers *are* out there. Anyway, RT's
goal for
> the co-op project is to allow this kind of thing, so people
outside RT
> can request and submit content. That, by itself, won't solve
the
> problem, IMO, because I don't think our problems today fall
into two
> categories: 1) the docs don't exist 2) it exists, but we can't
find
> it. I think #2 is the much bigger issue. If so, the problem we
> *really* need to solve is the organization and search
capability.
>
> In the meantime, if you have *specific* examples of things
that have
> frustrated you, for whatever reason, post them here with a
[docs] tag
> of some kind in the subject (maybe [docs//needed] ?), set up a
group
> on AltMe, or mail them to me (that's a last resort as I tend
to...
> what was I saying?). Some of us have forgotten how non-obvious
certain
> things are because they seem obvious in hindsight.
>
> You should never spend too much time banging your head against
the
> wall with REBOL; the community here is a big part of what
REBOL is.
> Just type "[need-help] <subject>". :)
>
> -- Gregg
>
> --
> 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.15/49 - Release Date:
7/14/2005
>
>
--
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.323 / Virus Database: 267.8.16/50 - Release Date: 7/15/2005
--
To unsubscribe from the list, just send an email to
lists at rebol.com with unsubscribe as the subject.
