Comments on: R3 Documentation Plan
Update: R3 Docs can be found here.
I just wrote a long article describing our documentation situation for R3, and what direction we will be taking. Unfortunately, I made the mistake of writing it directly in the web text-area box, and it went poof. But, I think that's a good thing, because who wants to read a long article about how documentation is like an iceberg (its huge mass is hidden from view.)
Instead, let me simply summarize the situation:
- DocBase, our document wiki, works just fine as an open-access archive for experimental, preliminary, side-notes, and other such documents. Certainly, it's not perfect, but we will keep using it.
- In addition to those DocBase pages, we have a large archive of existing R2 documentation, known as the R2 Manuals and Dictionary. They are written in MakeDoc and processed with a few lean-but-mean REBOL scripts.
- There is an advantage to using REBOL and MakeDoc, mainly that we can manipulate (convert, format, index, transfer, backup, publish) the pages very easily. In fact, we are able to scan, index, format, merge, and store the entire document base of 450+ files in less than 0.7 seconds on our Linux server. Frankly, this saves a lot of time.
Therefore, I've decided:
- The DocBase wiki will continue to be used for storing our developer-oriented, articles, notes, specs, etc.
- MakeDoc will be used for the official manuals, including the function dictionary, datatype glossary, and error message catalog. It will be processed with REBOL.
- We will be substantially reorganizing and updating the manuals for R3.
- We will use the WIP Wiki (REBOL-based, how we manage our various websites), for developers to access the above manuals via an edit link on each page.
- Specific users of DevBase will have direct access to the documentation via the DevBase ranking mechanism. That means that the official docs can only be modified by those experts.
- Any user who views the documentation can post a note/comment on it, to point out errors or make suggestions. Those postings will be cross posted to DevBase.
- For anything else, any and all users are welcome to post pages in the DocBase wiki.
8 Comments Comments:
Henrik
10-Feb-2009 13:51:37 |
Unfortunately, I made the mistake of writing it directly in the web text-area box, and it went poof.
Fortunately this will never be a problem in ReBrowser. :-) (I hope...) | kib2
11-Feb-2009 15:44:38 |
Hi Carl,
after reading through the DocBase page, it is said that we can have a PDF output, but I just can't find anything for this purpose.
Also, it could be a good idea to have a (La/Xe/Te)TeX backend for the docs (I know, I can write one myself, but I'm just starting playing with your beautiful langage, so maybe in the future ?). | onetom
11-Feb-2009 19:57:55 |
Carl,
Just a few days ago I was searching the net for your WIP Wiki -- no luck.
I suppose it is not public yet, right?
Can you share with us, please?
I'm willing to base my whole web prescence on Rebol and I need a wiki for that too.
I had promising luck with webserv.r and blog.r so far:
http://sa.sse.hu/~onetom/blog.r
| Henrik
12-Feb-2009 1:52:03 |
onetom, the wiki is located here:
http://www.rebol.net/wiki/ | Henrik
12-Feb-2009 1:58:50 |
kib2,
The plan was (is?) to automatically parse through relevant wiki pages to convert them into a high quality PDF for printing into a book, but with Carl using Makedoc 3 to build official docs, his method seems better. Mediawiki is too big a mess to work with, through a script.
Feel free to build a TeX backend at any time, but I would like to see the specs on Makedoc 3 first. | -pekr-
12-Feb-2009 6:55:46 |
I would like to ask, what is the main difference of MakeDoc 3 to version 2? | onetom
20-Feb-2009 3:16:23 |
Henrik,
I was talking about the *WIP* wiki source code, which is written in rebol using makedoc.
I was expecting it to be accessible like the blog.r is accessible. | Henrik
20-Feb-2009 4:23:13 |
I see. Sorry. :-)
It will be accessible to the public soon. Carl needs to fix user accounts for it first. |
Post a Comment:
You can post a comment here. Keep it on-topic.
|
