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
|
