Comments on: Status: climbing out of the doc pit

Did you ever see that TV ad, "I've fallen down and I can't get up."

Every few years I fall into a huge hole in the ground. Let's call it the doc pit (no, not a cave... because unlike the REBOL cave, the pit is full of tar where progress is tedious and dull.)

This time the pit has me faced with updating the official REBOL Users Guide documentation for REBOL 3. It's a huge task, editing hundreds of pages... but it must be done.

As I mentioned earlier in my main blog, I've decided to put the full force of REBOL into solving this problem. Good progress has been made, and I think you'll like the results.

As I may have mentioned, for these doc changes, I don't plan on doing it all myself. My goal has been to formalize and build a simple, organized (and non-complex) structure, and get it into a basic presentable form.

Then, it's open for those of you who are motivated to add notes, comments, sections, examples, and fix typos.

It's all accessible via the REBOL WIP Wiki and users with DevBase (RebDev) accounts can access it using the same username and password.

I've got a short list to finish today, then I can climb out of the pit, and get back to "more important things" (as if docs aren't important).

4 Comments

Comments:

Kai 18-Feb-2009 15:30:17	http://www.rebol.com/r3/docs/doc.html is broken....
shadwolf 19-Feb-2009 3:02:16	/em sends a rope to Carl ^^ Well of course if your alone writing the doc that will take years. An meanwhile R3 doesn't advance. But a fun way to work would be for you to make the chapter titles and for the community to fill the chapters with examples etc...
Norm 19-Feb-2009 9:06:34	I would suggest that good (peer reviewed) books be made, out of the Reference and User Guide. Free pdf, and modest Amazon in print price. I have experienced on demand edition lately; a good Latex class makes good milage. Instead of a user guide, we first need a small reference, with proper BNF syntax, to memorize the semantics of the language (100-120 pages, 6x9 perfectbound, is a good handy size).
Edoc 19-Feb-2009 10:59:32	I don't know if you do this, but it's often a good idea to create notes as you go along. Some sample questions: What is the high-level purpose of the functionality? How does it fit within the feature set of the language? What are the primary and secondary use-cases? Is the feature closely related to other features or functions? What are the boundaries/limits, side-effects and memory/speed trade-offs? Are there any nuances that newbies should know about, or guru-level aspects? If can save these types of notes, you'll probably find that you already have over half of the documentation drafted-- enough for others to edit and elaborate upon.

Post a Comment:

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