New Documentation Engine Goes Beta
The new official REBOL users guide and reference is now in beta on www.REBOL.com.
Here are the highlights:
- It combines all pages from the REBOL/Core Users Guide, the Function Dictionary, sections on Datatypes and Error messages. See the "pending" notes below. Everything is interlinked. So, when you see the function name append in the text, clicking it will take you to the function definition page. The same is true for datatypes and other key elements.
- It's now a wiki. Everything is editable over the web. Experts in our community can edit these pages, improve its content, keep it accurate, fix typos, etc. (I should stress the word "experts". Not just anyone can directly edit these doc pages, only registered DevBase (RebDev) users of high rank. But, anyone and everyone will soon be able to add comments to sections. More on that below.)
- It's powered by REBOL. So we have full control over every aspect of how it works, structure, format, user accounts, logging, backup, search, and special scripted actions for mass changes. (And, size is LM: 48K, LMF: 32K, LMFC: 11K - a rough gauge indicating minimal complexity.)
- It uses MakeDoc3 markup format. It's leaner, meaner, and cleaner than MakeDoc2. It's now trivial to build hyper-links to elements like concepts, functions, and errors. More docs on MD3 are pending.
Some notes and pending changes:
- It's just a start. The content needs major work. Other than the new Guide section, the main source for the content is the R2 manual, which is out of date, written for a different audience, and generally needs major work. There are various missing sections.
- Linkage to user comments. We'll be adding a user comments link to each section. These comments will be stored in the DocBase wiki, which is much more open, but also not as "official". This is a good solution to the quality vs quantity problem.
- Search will be "improved". Actually, a better word is googlized. We'll enable Google for searching the document. Although the current search works well, we need to balance out the server load, and Google let's us do that at no extra cost. (Note, editors will still have access to the current search, which is better at some things, like locating editorial markup tags.)
Now finally:
3 Comments
|
