REBOL 3 Docs Guide Concepts Functions Datatypes Errors

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 usersUsers 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 knowledgeUsers 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 codingUsers 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:

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:

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:

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

The reference sections are:

FunctionsDescribes every built-in function of the language. Combines each function's embedded specification with a more detailed description.
DatatypesDescribes each of the datatypes of the language.
System objectDescribes each field of the system object, its purpose, allowed variations, etc.
ErrorsExplains 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 levelaccess 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 backbuttons move you sequentially between pages within the same section.
Sidebar menulets you hop around to different parts of the same section. (Pending)
Hyper-linkswithin the text take you directly to any page.
Searchlets 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.


  Table of Contents REBOL.com - WIP Wiki Feedback Admin