If you are an experienced REBOLer, you may have come to frustrations about how to do a specific thing and not being able to find good documentation about it. The documentation in the past was generally made by Carl Sassenrath, inventor of REBOL, alone.

While the documentation there is, is OK, it's very sparse and some existing features that are greatly lusted for, by the REBOL community, are simply not documented, so we can't use them.
The amount of contributions you could make, was pointing out spelling errors, only to find them uncorrected for months, if ever.
Another problem is that documentation only exists in a reasonably new version in HTML format.

For REBOL3 this changes completely. Similarly to how REBOL3 in itself becomes partly open source, the documentation changes to an open source project: A Wiki. This Wiki is called DocBase and it will be the primary resource for REBOL documentation. How fast the community is contributing to this Wiki is already showing how advantageous it is to outsource documentation writing: As of this blog post DocBase consists of about 85 webpages. But there is a long way to go. DocBase documents less than half of the current R3 feature set.

This blog post attempts to describe what the plan is for now and how you as a developer or user may be able to help. The plan might change over time, if we come up with better ideas than we have now.

Currently DocBase is based on MediaWiki, the same wiki system used to power Wikipedia and many other Wiki sites. Why do we use that and not a REBOL system? There was no time to build one and MediaWiki has shown itself to be reliable enough for the task (webbased editing and tracking of changes), even if it's a little heavy to use.

The location for DocBase is still not public. The skin chosen for DocBase is currently resembling that of Wikipedia, but I hope we can get something much better in.

REBOL3 DocBase Main Page

DocBase Structure

The current structure of DocBase is a little haphazard. As any MediaWiki based Wiki, DocBase is essentially a flat pool of documents. There is no real hierarchy possible in the document structure, so the hierarchy must be defined by ourselves. Several selfdesignated types of documentation exist:

• Design Documents
• Reference Manual
• VID3
• Cookbooks
• Testing Notes

While more pools will be added as we go along, some of these pools are temporary for use during R3 development, such as design documents and testing notes. This is necessary in order to as quickly as possible refer to test results and temporary documentation for between developers for new tools and features in R3.

Reference Manuals

Some requirements were set up for the reference manuals:

• They must be automatically built from the internal functions present in REBOL3, using REBOL3's own help text.
• Developers must be able to add notes about a function in true Wiki fashion
• Users must be able to comment on a function.
• All dialects must now be a part of the reference manual.
• They must synchronize notes and changes from a REBOL3 version of the word browser for REBOL2.

The reference manual must be built and maintained with a minimum of hassle, just using REBOL based build scripts. Over time, the amount of work done to maintain it, must get smaller with script improvements. This work is being done now.

Tools

For DocBase, a small toolset called Wiki Tools has been developed. This essentially allows you to download, upload or synchronize text files directly into DocBase using a small dialect. The only requirement is that a user is created in DocBase for you to upload or change existing pages.
The tool is still very basic and console only, but once REBOL3 gets better text editing facilities, it should be possible to build a simple DocBase page editing tool on top of it, so we can edit pages without actually having to visit DocBase. This tool can eventually also grow into the new word browser, although this has not been finally decided.

Cookbooks

You may also be familiar with the Cookbook concept that was introduced on rebol.com a few years ago. The idea was then to offer tidbits of information to users to quickly get started with a a particular area of REBOL. As quickly as it got started, it was halted and has not grown beyond the 100 article mark for years. Well, now it will be able to freely grow, thanks to you! But the idea of cookbooks must change.

We as REBOLers have suffered too much with loss of documentation, documentation only available in specific languages (particularly French) and plain poor or no documentation for a product.
The basic philosophy with cookbook recipes is therefore now: If an idea is not written down, it will most likely be lost. So you can see the importance of this section of DocBase.

With DocBase, a special Cookbooks area has been designated particularly for REBOLers, who want to contribute an article (recipe) about a specific subject that can be hard to explain in a few words, is a lengthy, difficult procedure, or is a tutorial in how to use a product created with REBOL3. REBOL Cookbooks consist of recipes where each recipe has a title, difficulty rating and author name. Each cookbook represents a particular topic.


The Cookbooks List is itself a Cookbook as shown in the page header

Each recipe is then stored in the Cookbooks List, which lists all recipes in all cookbooks. The current cookbooks are:

• Low- and Mid-Level Networking
• REBOL/Services
• Rebcode
• Low Level Graphics
• VID
• OpenGL
• Data Processing
• Security
• Scripting
• Plugin
• Modules
• Tasking
• File Management
• Error Handling
• Debugging
• Dates and Times
• Console
• REBOL Language
• Audio
• Numbers and Math
• Mediatypes
• System
• Embedded
• Windows
• MacOSX
• Linux
• Documentation

This list will surely grow in the future. Perhaps there are a few hints on coming functionality here? Hmmm...

Here's another job that needs to be done: Take the current R2 cookbook recipes and convert them to R3 for use in this cookbook list. Who's up for the task?

Another important aspect is that you can request cookbook recipes to be made. If there is a topic you'd like described in depth, hopefully a developer will take up the task and make that recipe.

Printed Manual

Another ambition is to get a printed manual created directly from DocBase. No, it's not just about going to the webbrowser print menu and ask it to print. It will have to be a real book with real typography, structured like a real book. Since DocBase is essentially a flat structure of documents, this will be a difficult project and one there will be a requirement for much help on. Discussions on how exactly to build the book have resulted in the following:

In true REBOL fashion, tools will be required to build the book at regular intervals into PDF format. This is most likely to happen by handpicking predefined pages and chunks of text from DocBase. The handpicking should be done by a script, for assembly into the book.

This is slated to be a future project, once DocBase has reached a certain structure and stability and will require 1-2 dedicated people to build.

Similarly to the reference manuals, the goal is also to avoid too much maintenance over time.

The Role of the Wikibook

In the past, when REBOL3 was still a secret project, I started a project called REBOL WikiBook. This was established on the WikiBooks site (a sister site to Wikipedia). It was shown that a book could grow incredibly quickly through the contributions of several REBOL experts. However when REBOL3 was announced, growth of the book suddenly stopped, because there was now a possibility that it would be a waste of time to build a complete book around REBOL2. It serves now only as a reference for a few things that were not originally documented properly.

I expect that the WikiBook will be abandoned, but before that happens, the best content is being incorporated into DocBase. Another reason is to avoid confusion over which book to read.

Conclusion

So to round up on the tasks:

Improve the presentation - Make a better looking DocBase.
DocBase Structure - Over time, the structure tightens up and temporary documents are removed or sectioned out. This will be handled by the core developers themselves.
Cookbook Recipes - Get those tutorials and articles written.
Convert R2 cookbook into R3 recipes - They are sitting on the rebol.com site, waiting for you to convert them.
Centralize Documentation - Scattered bits of documentation should be gathered under DocBase.
Create a Print Book - This is a complex task, but should be possible to do.
Decommission the WikiBook - Over time, when most information has been moved into DocBase, this will happen.

Now... back to work.