Comments on: 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.)
i love this new documentation full R3 support !-)|
|Sam D. |
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.
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.