REBOL 3 Document Structure and Objectives

This page outlines our organizational objectives for this documentation, and how we formed its structure based on them.

However, it should be noted, this is a goal and reaching it involves editing and improving hundreds of pages of documentation (740 pages). Please understand that it will take some time to achieve it.

Contents

Objectives

Usage patterns

We built this document based on observations about the usage patterns of users over past years.

We have seen these primary patterns:

New users	Users who are just getting started and want to learn the basics quickly, with links to deeper knowledge. Also, we've noticed that many new users are not interested in reading long chapters or descriptions.
Deeper knowledge	Users who want (or need) a more complete understanding of specific major features or concepts of the language. This is what you read if you don't get what you need from the above section.
Daily coding	Users who need specific details about functions, datatypes, errors, and the system object.

We also recognize another important pattern: users often want to contribute to the documentation. They can:

• Fix small typos they may find while reading a section.
• Add or edit a paragraph to make meaning more clear and obvious.
• Add or improve on the examples.

It was important for us to support that via a feedback mechanism (for casual users) and also by direct editing of content (for expert users).

Additional objectives

In addition to supporting the above usage patterns, we also wanted:

• Separate "dimensions" (domains or contexts) of information. A tutorial is not a manual, and a manual is not a reference. The structure we've implemented makes those sections clearly separate (but highly interlinked.)
• Rapid navigation to major sections. Those are the buttons at the top of every page.
• Menu-oriented sidebar navigation of each section. (Not yet provided, but it's a goal.)
• Easy sequential navigation of pages. Although less important, we wanted to preserve a book-like sequencing of information. That's the reason for the next and back links.
• Effective use of search for finding content. For a number of reasons, our earlier manuals did not respond to search well. We found that if you Googled "REBOL protocols" you would not easily find the primary chapter on that topic. We had to fix that.
• Abundant use of hyper-links to all related content. A user reading a tutorial can find conceptual links and reference links for more detail.
• Use of reasonably named hyper-links to all content, including guide, concepts, functions, datatypes, errors, and system object sections. So, links look like concepts/series.html and functions/insert.html.
• Support for internationalization (localization) of the document, on a per-page basis.

Relationship to DocBase

This document covers REBOL as a language, and it is not a replacement for a general knowledge base, as supported by DocBase.

DocBase provides many detailed articles and notes. Those that need to be part of this manual or reference will be moved here. For example, the description of the graphical object datatype gob! belongs here.

In addition, DocBase includes many articles that are proposals, describe implementation details, lower level design, special interfaces, and more.

Organization

Primary sections

This document is divided into two primary categories: manuals and references.

The manual sections are:

Guide	Intention: to give users a quick, but highly hyper-linked, introduction to the language. It introduces the main ideas, but does not go into details.
Concepts	Intention: to provide detailed, in-depth descriptions of all REBOL concepts. Also includes graphics, sound and other such modules.

The reference sections are:

Functions	Describes every built-in function of the language. Combines each function's embedded specification with a more detailed description.
Datatypes	Describes each of the datatypes of the language.
System object	Describes each field of the system object, its purpose, allowed variations, etc.
Errors	Explains in detail each error message, how it happens, and what it means.

Other reference sections may be added. (For example, plugin modules and standard Internet protocols.)

Navigation

These are the primary methods of document navigation that are supported:

Top level	access is provided with the document header bar at the top of each page. These are the primary sections of the document.
TOC	(table of contents) pages are provided for each major section.
Next and back	buttons move you sequentially between pages within the same section.
Sidebar menu	lets you hop around to different parts of the same section. (Pending)
Hyper-links	within the text take you directly to any page.
Search	lets you scan the entire document for specific keywords.

Localization (Internationalization)

We want to support translations of this documentation and provide an easy way to keep them synchronized with the master content.

In general, we will be providing alternate URL's for other languages, similar to what you find in other document systems. For example r3/docs/fr/functions/absolute.html would be the URL for the French translation of the absolute function.

However, before we begin supporting translations, we really need to finish reworking, restructuring (and finishing new sections) of this content for the REBOL 3.0 changes.

Maintaining quality

The REBOL language is a master design, built on computer architectural principles. It is not built like a bazaar, with twisty little passages that are nailed on at the whim of every user.

We don't think that a language reference manual should be written by beginners or by people who only have time to think lightly about the concepts. Although we allow editing of this manual, direct page modification is only allowed by qualified REBOL developers and document experts. This is done to preserve the quality of the documentation.

Although any user can submit corrections to typos or add to content via the feedback mechanism, in order to edit these pages, a user needs an account on DevBase (chat messaging) with a sufficient ranking to certify that they know what they are doing. In this way we can keep the manual true to the principles that make the language special.