Comments on: REBOL Document Searching, DocBase Nutshell
REBOL Technologies

Comments on: REBOL Document Searching, DocBase Nutshell

Carl Sassenrath, CTO
REBOL Technologies
8-Aug-2006 0:05 GMT

Article #0286
Main page || Index || Prior Article [0285] || Next Article [0287] || 8 Comments || Send feedback

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.

Name:

Blog id:

CS-0286


Comment:


 Note: HTML tags allowed for: b i u li ol ul font p br pre tt blockquote
 
 

This is a technical blog related to the above topic. We reserve the right to remove comments that are off-topic, irrelevant links, advertisements, spams, personal attacks, politics, religion, etc.

Updated 3-Dec-2023   -   Copyright Carl Sassenrath   -   WWW.REBOL.COM   -   Edit   -   Blogger Source Code