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

Updated 14-Nov-2024   -   Copyright Carl Sassenrath   -   WWW.REBOL.COM   -   Edit   -   Blogger Source Code