Comments on: New Documentation Engine Goes Beta
REBOL Technologies

Comments on: New Documentation Engine Goes Beta

Carl Sassenrath, CTO
REBOL Technologies
20-Feb-2009 20:03 GMT

Article #0392
Main page || Index || Prior Article [0391] || Next Article [0393] || 3 Comments || Send feedback

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

Comments:

claude
20-Feb-2009 14:04:59
i love this new documentation full R3 support !-)
Sam D.
21-Feb-2009 18:23:13
There are some views on page design that consider that long line lengths across the page are harder to read than shorter line lengths. Content set in with say a 70% width might be easier on the eyes.

Long page lengths means lots of scrolling, something that can be tedious. A short page is easier to contemplate. Maybe a 2 frame HTML document might be better, one frame being a contents page for navigation links to content.

Search engines may have once had trouble searching framed documents, but perhaps this has changed.

Carl Sassenrath
24-Feb-2009 10:59:57
Claude: thanks!

Sam D.: We agree on the trade-offs of width. That's why we made the old document a specific width. For the new doc, we decided to let the user decide. We've used a very free form layout method, so you, the user, can decide to make it narrow or wide. These days, I think most users know how.

And, we do plan to add sidebar navigation. That should help with the width too.

Post a Comment:

You can post a comment here. Keep it on-topic.

Name:

Blog id:

CS-0392


Comment:


 Note: HTML tags allowed for: b i u li ol ul font p br pre tt blockquote
 
 

This is a technical blog related to the above topic. We reserve the right to remove comments that are off-topic, irrelevant links, advertisements, spams, personal attacks, politics, religion, etc.

Updated 24-Nov-2017   -   Copyright Carl Sassenrath   -   WWW.REBOL.COM   -   Edit   -   Blogger Source Code