Bernie, Steven, et al These are all good and valid comments about the state of REBOL docs. In some cases there aren't any docs, and in other cases there are too many docs scattered about and sometimes they're very similar.
Examples tend to favor conciseness very heavily; good for experts, not for newbies. It's kind of a catch-22. People want to show how it takes very little REBOL code to do things, but that means leveraging REBOL in ways that make it harder for newbies to understand. By using examples that are easy to understand--because they look like examples in other languages--it can be hard to see that REBOL is different. And, yes, REBOL's flexibility is both a boon and a curse. :) The idea of embedded documentation is based on Literate Programming, which could actually be a pretty easy thing to do in REBOL, with make-doc; just have an emitter spit out the code sections as a .r file. I can't say why REBOL clicks OK for some folks and not for others, but I *can* say that RT really does want to improve the state of REBOL docs dramatically. There have been a lot of good comments here lately and I'm trying to mark them so they don't get lost. If anyone has specific examples of docs for other languages that they feel have helped them, pass them on to me, or post them here or on AltMe. -- Gregg -- To unsubscribe from the list, just send an email to lists at rebol.com with unsubscribe as the subject.
