The apps are what people are going to try first and say "Wow, this is awesome! I should spend time learning the language and see what I can build in it." ... but then they start asking around for documentation and tutorials and the only thing we have to offer is 10+ year old docs that are no longer relevant (i.e. vid dialect and other unsupported things), conflict between each other (i.e. r2 vs r3) or have too many semantic differences from Ren-C.
So we definitely need something to inspire people, but then we need something official, modern and up-to-date to learn from too, or else we may get a huge influx of interest and then it just dies off right away... and I think that would be hard to recover from.
The problem I see is there is very few active people here, and too much work to go around, and I don't know how to fix that. I've started to look at the reboldocs site again, and I'm hoping to get some momentum on the documentation there. But it will be challenging because writing always takes a lot of time and there is a lot to cover.
If we were to put together a wishlist of where people are needed, I would suggest something like this as a minimum ...
2 people working on Ren-C (@hostilefork on the core, someone else on the JavaScript extension)
3 - 4 people working on web apps using the JavaScript extension (focus should be on one app each, that is continuously polished until it is production ready)
2 people working on documentation for Ren-C
We don't have these kind of numbers, and I'm not at liberty to tell people what to work on (or how to do it)... but I think this is where the need is, if anyone is looking to contribute. So I don't know what the solution is at the moment. Does anyone have any carrots they could throw over to the Red side?
We have not--as yet--done much in the way of outreach to try to bring in more people.
This is why I am thinking that delivering small...entertaining...educational things is worth it.
There is the option of focusing on Rebol2 compatibility through emulation.
I do want to build that compatibility layer, but it's work and testing.
This is why I kind of want to rein expectations in. But I don't want to rein it in to where you think it's too unimportant to participate. And @gchiu clearly wants to push it bigger.
I vote against the web framework goal. I vote we find something smaller we all enjoy developing and seeing get better day by day. If it's not the tutorial...then okay, I guess? I thought that was a kill-two-birds-with-one-stone kind of idea.
If no one else likes my idea, should we pick UI Builder? Power calculator? Chess? Italian Bible Search Tool? None of these were on my radar until people started making them.
I still think my plan is the best one. I haven't been convinced otherwise. This thread is about me wanting to convince you, vs. having to swim upstream against expectations which cannot be met.
Nope. While my model of them varies, it's always somewhere on the spectrum between ignorance and malice. Their motives clearly had elements of corruption even before the cryptocurrency debacle (outside of the fact that all of that's mostly a scam, there's probably someone out there mad about the -95.75 ROI).
We're effectively at war. Though people may freely discuss Red here or on SO chat, you won't get the same courtesy over there regarding Ren-C. You can try talking to them and see how well that goes if you like.
"Our two remaining reporters worked for weeks on that piece and we also made the paper smaller so Michael could read it on the train ..." - That video is hilarious!
The tutorial is small and educational, but entertaining, mmm, not so much...
Having said that, maybe this is the key. What if we made the tutorial into something that builds an end product, like a game. It would have to be a small game (or whatever the end product should be), but it could be done in a way where each step slowly builds your understanding of the Ren-C syntax, but at the same time you're building something fun and you get to play with it at the end.
I'm all for gamification. I bring up code golf because that's a game domain I am personally interested in...
I've oft-mentioned my affection for SpaceChem. Which I think is brilliant, and at its core it is a "code golf" game, just made a bit more visceral through circuits-and-multithreading-as-told-through-fake-chemistry:
The idea of the tutorial giving you "levels" and having you complete each level to get to a new one... offering you limited parts and grading you on how many interpreter ticks you used vs. how large your program is... is something I do want to do.
I'm open to us saying it's a game, but games tend to need graphics. Is there a way of visualizing Rebol-isms to where GROUP! is drawn a way, and BLOCK! another way, to teach the evaluator? Can we give puzzles that are actually running some kind of Ender's Game of the evaluator?
I'm happy to volunteer as one of the writers/editor for project documentation. I'm not a programmer/developer/software-engineer and so I will need to lean fairly heavily on Brian for insight into aspects of the language design as well as other skilled contributors in this small community.
I have some ideas for gamifying a tutorial. For now I will focus on the content, framework of topics/core concepts and pull examples together (while identifying gaps) and trying a few experiments to figure an interactive approach to showcase the cool new language features. If we're using WASM (and I think we should), I envision something like an interactive kiosk with progress tracking/saving, checkpoints and perhaps some other features. If some level of graphics/sprites are available we might adjust the balance of text/reference content and boost the interactivity/graphics. This latter part isn't my strong suit, but the writing, editing and basic content management/publishing is something I can help push forward.
Just try to improve the embedded help. Try help/doc default and it will take you to help pages on github where you can add to the embedded help with examples as I did there on that page. This is supposed to be a collaborative effort but not a single PR was made for it from anyone else.
Take an existing open source book and rewrite it for ren-c ( eg maybe take some examples from F Jouens books
Work on Carl's docs and port them but he has asserted his copyright on those so that may be tricky
Take a book like Starting Forth, a real classic which the text is available, and port it to ren-c. Trouble is, although the text is available, it's in LaTeX
The problem is, if the people writing code do this, they won't have time to write code. So, people who don't write code but have a good understanding of Rebol/renc need to do this.
Here's another idea. A documentation manager collects the topics that need writing. They then break it down into chapters, or pages or paragraphs, sketches out what needs writing, and then puts it out there for people to volunteer to tackle. Breaking it up like this is a bit like square foot gardening; make it into manageable chunks for people to work on.
I'm for improving docs:
1: add sort of links in embedded help, e.g. some SEE ALSO section
2: automate making of docs from source
3: exploit existing tests to make a DEMO function
I like these ideas. It gives you a framework to work from (i.e. for the type of chapters and content to include) that is known to work well. Another book to consider emulating is Automate the Boring Stuff with Python. It is very practical and keeps beginners interested by focusing on projects you will likely find in the real world.
I started thinking about books too, when I was looking at our documentation again and another idea I had was we could turn the book into an app similar to the ones UI Builder exports. It could be a single HTML file that contains the Ren-C interpreter. This would allow you to embed a console in the book, so that you could try out the examples as you read about them. The chapters would just be divs that are hidden/shown as you navigate through the book.
Modern Rebol:An Interactive Guide to Ren-C
Anyway, just throwing it out there as a future possibility. The main thing right now is just writing the content, as that is the hard part. We can figure out the rest later.
If you want to start adding this documentation to the rebol docs site then let me know, and I'll revive that repository and write up a tutorial and how to get started with that.
Thanks. I have that Python book, by the way-- it's a very good one.
I'm in favor of an immersive and practical approach. Don't spend a whole lot of time on the background (but link to reference material)-- cover some of basics (values, blocks, words, fns) and wade carefully into some common real-world examples.
Really like the idea of embedding the interpreter. I'd like to shoot for a form an interactive kiosk or CBT (computer based training) program, with benefits of an executable and a web site (locally searchable, printable).
You're right, ultimately there is likely to be a lot of content. My preference is to provide enough content to cover a small number of real-world examples, and not to aim for comprehensiveness at this early point. We'll work on expanding the content organically as the project gains notoriety.
Documentation is something that sounds nice in theory. And certainly, following a proven formula for a book that has already worked sounds like a good idea.
But I want to be wary of following the pattern of what Rebol already did: dump a bunch of documentation on people without ever getting the motivations right...focusing on what instead of why. It's what Red is trying again, and there are things like Red by Example, which are arguably better than nothing...but still, don't give the impression I'm looking for.
I kind of want to flip the expectations here, conveying the why, and inviting people to become part of the process of helping define the what. And when it comes to the language, I don't want any selling of snake oil or misdirection. Everything should be explainable and justifiable to a computer sophisticate.
It would be better in my view to teach people one constrained dialect that they could think of as cool, and not teach them a zillion features. When they find it useful and want to explore how it's done, they will bring the motivation. That motivation should come with more curiosity than expectations.
So I'm already infinitely more on board with getting a good online workbench for using PARSE...uploading and downloading your data with drag & drop. And maybe the whole language is not taught for what you can put in the GROUP!s as code, but you get a few stock things you can do. Then, the code in GROUP!s is taught as a "bit of a black art" that is in the development stage, and people can come join and get involved in designing it.
Again, I'm talking about setting expectations that can be met. Documenting and getting people into the usage of PARSE alone is a huge project. We don't want bigger than that, and "the whole language" is going to be be bigger than that, by definition.
I think we're aligned. Personally I think PARSE is the most practical part of Rebol (and certainly a gateway to dialects) -- around half of the tutorial should be devoted to it. Until you get to PARSE, much of Rebol is a sort of quirky questionable language that for most devs will smack of being too clever for it's own good, i.e., being different more for the purpose of being different than being truly innovative.
I was originally thinking about a tutorial where you actually build a game, but playing one is an interesting idea too. I threw this together over the last couple nights. You might like it if you're into badly written adventure retro games with a D&D fan fiction immersive fantasy world.
I was just having some fun. It needs a lot of polish, more in-depth tutorials and maybe even a genre change... but possibly, maybe, it will inspire some further ideas. ¯\_(ツ)_/¯
Try entering wrong answers and turning on your audio to get the full, uhm, effect.
You can type "cheat" to skip through most parts, or "fight" to go directly to the battle scene. Also, the audio works better on Firefox. There appears to be some random syncing issues occurring on Chrome.
Uh oh, I died... (I should probably be more careful, this project has a pretty low bus mummy factor.)
Very interesting start! This sets a standard and some styling for the tutorial--and it's the first we've seen...so I don't have any reservations about saying it is the very best we've seen!
The most important thing in my view is the kind of "wiki" mechanic, that things can get better by someone taking a few minutes to make a small improvement...and that these improvements add up. So if I could propose a "next step" it would be that we figure out how to make this tutorial pattern easier, to let people start working through their own narratives.
I thought that some kind of way that a Trello board becomes executable would be neat, and what you might be calling a "level" would be a column on the board. Trello is great for rearranging and thinking. It's not so good with versioning, so we'd need some kind of way of backing up the board on an at-least-daily basis and getting cards back. But I'd rather leverage a pre-existing UI of that type vs. be stuck trying to build one right now in Rebol!
Yea, for sure. I ran into some limitations with the print function where I couldn't get the HTML layout I wanted in some parts or highlight text in certain ways. There should also be some standard functions to do things like ask a question and verify the input matches a specific answer or is one of a series of correct answers. Also, some way to "do" certain types of input and be able to capture syntax errors and report back the issue in a beginner-friendly type of way.
I am not particularly stuck on this implementation, but it is a working prototype that we can use to experiment / test new design changes with and see if it makes creating a tutorial easier. I burned through writing the code, and so there is a lot of ugly hacks and un-optimized things going on. I think "next steps" is I'll start re-factoring things and through this process begin submitting PRs for standard functionality we could implement.
I also saw the comments you submitted on my branch. So, thank you for that. I haven't had a chance to look at those in-depth yet, but will do in the following days.
Going a little further with some previous comments...I wonder, @BrianOtto, if the first tutorial to cover should be PARSE-focused.
Despite there being some lingering questions, I was using PARSE for a task this week and feeling pretty pleased with it. I even finally understood why WHILE exists...once the ANY and SOME constructs were fixed to be what I think they were intended to do!
As I've mentioned before, if you are using PARSE it starts to motivate learning the quirkiness of the rest of the language. Whether you like the imperative portion of the language at first isn't that important if you like PARSE... it's what you have. It may grow on you to where you start seeing and wanting to imagine the potential (custom function generators, dialects, etc.) You have to understand it's dressed up as a "normal" language, but not one...and I could certainly see why many people would think it just weird if they don't get the trick.
And in terms of game goals, PARSE can have a clear one to start with. Get to the end of the input. Higher levels can go on from there.
Modern Rebol: An Interactive Guide to Ren-C
(I should probably be more careful, this project has a pretty low