Comments on: REBOL Document Searching, DocBase Nutshell
The other day, while browsing for a specific REBOL example, I hit
this message in another language's forum:
The docs for rebol are few and horrendous. the above example
i wrote when i first got into rebol but "system/script/args"
took me four hours to find. i had to comb through the rebol
script library. before i found the example.
It seemed like an odd statement. I was puzzled by it. The
Scripts Chapter of the REBOL Users Guide describes the args
field and gives a simple example. Using that, any user should be
able to write a few test scripts and understand it quite well.
It's not hard to find; it's right there in the manual!
But, the person who posted the message seemed like no dummy.
Why was it a problem for him to find that code?
Then, the answer struck me: He, like most programmers, was
probably Googling for the solution.
I decided to test my theory. I googled "rebol program args",
"rebol command args", "rebol command line args", "rebol
arguments", and a few others. Hmmm, not good! They didn't produce
great results. You'd have to know REBOL pretty well to interpret
the results. I found that the user needed to google "rebol
script arguments" (or args) to get reasonably close to the
Script Chapter link.
So, my theory may be correct. Of course, I tried googling the
same query for a few other languages, and none of them produced
useful results either; so, we are on par with other languages
in that regard.
However, to draw a conclusion from the experience, I'd have to say
that the chapters of the REBOL on-line guides are probably far too
large to be indexed well by most search engines. For example, the
Series chapter is 43 pages long and covers a lot of concepts. A
search engine will see it as a huge "blah, blah, blah" of text that
make it difficult to hash out good reference triggers.
Note that our original motivation for keeping the chapters long was
to make them easier to print as a single chapter. But, that seems a
bit weak these days when most serious users prefer the rapid results
of search engines to flipping through pages of paper. Yes, paper
copies have their uses, don't get me wrong, but the online docs
would be better off modified to fit the search engine model, and we can provide a combined PDF file for printable copies. (This is
not a new idea. Java, GNU, MIT, and many others post in more
granular levels of detail, probably for that reason.)
I'm mentioning this documentation issue because the new REBOL
DocBase will be making substantial changes to how our documentation
is managed, posted, and kept updated. In a nutshell, each section of
the documentation will be stored separately in a database. Then
relational database techniques will be used to build the online
guides, tutorials, indexes, and content summaries (e.g. quickstart
guides). Also, the docs will be wikified to allow developers
to make changes and contributions (similar to Wikipedia).
8 Comments Comments:
Andrew
9-Aug-2006 2:52 |
:)
A wiki for REBOL would be great! Two thumbs up. | Henrik
9-Aug-2006 4:54 |
A thing I really like from the PHP documentation is that you can type in functions directly in the URL and get help for them immediately. Say you want to find the ECHO function:
http://dk.php.net/echo
or FOREACH loops:
http://dk.php.net/foreach
It's just another approach at having a simple lookup mechanism. | MikeL
9-Aug-2006 11:51 |
Carl,
The problems that you are planning to solve for REBOL documentation are common ones.
Maybe thinking how your solution could be commercialized would be prudent to consider in the design now. | Sunanda
10-Aug-2006 13:41 |
Google searches for
system/script/args rebol
find lots of useful things.
REBOL.org has its own search engine that also understands searches for paths, so this search:
http://www.rebol.org/cgi-bin/cgi...2Fscript%
2Fargs
finds all the scripts with that string. | Henrik
12-Aug-2006 5:23 |
A new code search engine called http://krugle.com/ has been created. It's pretty good and even links to the original REBOL documentation on rebol.com | Mario
17-Aug-2006 17:23:59 |
A friend that has always been reluctant about using REBOL recently had to use it for his work as he needed a quick solution involving automated http posting of data.
He browsed some docs suggested by me, searched the library and learned how to merge and change an existing couple of scripts to fit his needs.
It took two days and he told me that the learning curve is great! He programmed with a few C and PHP, before.
But he needed me to point him to the correct REBOL resources and docs. He still ignores AltME so no instant help could be given to him but from me.
IMHO Rebol needs a "starter kit", something like the Rebol.org Desktop Application or the Easy Draw and Easy VID along with an updated PDF/HTML/HyperNotes manual.
Links to editors and syntax highlighters for them should be provided in the "starter kit" too.
A good thing to add to Rebol Library is a real library mechanism: something like CPAN for Perl. A library of functions should be doable from a script. This will have advantages on howto docs and indexing.
The scripts library is really useful as a reference but has to be split in complete scripts and functions collections.
Finally, what's really missing is a "Path from another language" howto and this is also the most difficult part to breed for us as we already know where to search.
I tried to ask to some of the newcomers to the mailing list to keep a list of their questions and the accepted answers to create such a document but this is boring and the quicker one learns the easier the answer appears so it's not wrote down.
Maybe a monitor script to the mailing subscriptions or to the threads should help with this task.
After the REBOL teaching experiences of the last year (an "alpha" experiment) I'm tring to collect, in this new year, all the FAQs from the beginners (99% of my students know nothing about programming when they start) but this cannot fulfill the questions of people coming from other languages.
To close this prolix, confused, "before going to bed" comment I think that the "Wikipedia" like solution will be perfect if some tools to convert/update it from web to HyperNotes (for the "starter kit") are provided and if we "force" newbies to use it instead of the mailing list.
IMO this is in the REBOL philosophy: data is code and code is data and doc is data too. | Carl Sassenrath
17-Aug-2006 18:24:21 |
Good ideas and suggestions. This discussion is "near and dear" to me, because I want to make it easier for new users to learn REBOL. Success requires that the userbase always be expanding, and that new users stick with it (over the long run).
I agree that the beginner experience is a big problem. I can see the problem even here, in watching local kids (and my sons), working at learning REBOL. It seems that they really want to learn.
Many of these new users have no formal training in programming, and they do not have the patience to read the manual. These days, users want quick results, or at the very least, quick answers to their problems.
Also, when I look at other languages, I often find that it is a really good web resource (like those for Flash scripts) or a great book that make a huge difference.
I remember back 30 years ago when I was new to programming. I learned ALGOL, Pascal, BASIC, Logo, Forth, C, etc... and, for each, I remember a great beginner's book. For example, Forth had the fun and easy Starting Forth book by Leo Brodie. It is true that there were many other books on these languages, but there was always "the book" that you had to read. | Carl Sassenrath
17-Aug-2006 18:25:44 |
PS: I think the "starter kit" is a really good idea. Let's make sure we find a way to make that happen once REBOL 3.0 is released. |
Post a Comment:
You can post a comment here. Keep it on-topic.
|
