This document describes briefly the current state of Raku examples repo and asks for comments on plans related to it.
It is a rather old repo (created back in 2008), which contains various examples of Raku code and has means to present them as a website.
As in 2020, it has a number of drawbacks (some of them were described by Timo++ in Raku/user-experience#24):
- The website does not support some essential features (such as search, easy navigation)
- The website UI can be more of an eye-candy, especially considering the same UI is used on doc website
- Content is not organized nicely for the newcomers
- Its internals have some technical drawbacks, like relying on vim to do highlighting, being apart from latest achievements of doc repo team, etc
Over the last months I did some efforts on the technical side of things and minor content improvements:
- Tidying up the files
- Migrating serving to Cro
- Raku-related renaming
This work can be finished in not a long amount of time, but it appears the repo wants an overhaul rather than tidying. Right now, I am preparting grounds for putting up a quality UI for both documentation and examples websites.
When it comes to content, it is not so clear. I see several of directions we can head from here.
All existing examples in the repo are divided into two sections: cookbook and feature showcase.
When a user visits the website, two paths / categories are presented to them (besides goodies like a random example of the day, etc) (wording just expresses the idea): "If you want to look up some code for your $dayjob, go for a cookbook!" and "Don't know why do we have a Raku $feature? Let's find out!".
The first section contains organized, revised, extended examples from cookbook, mostly "mundane" world $dayjob tasks which you want to google up when typing "raku parse json", "raku download by url", "raku walk files recursively" and see some code, all divided into categories like "net", "file system" etc.
The second section contains organized by complexity levels (measured by, ahem, code length and arbitrary judgement of the one who revises the example). Various solutions to Euler problems, 99 problems, etc can go here when applicable. Those examples are "tagged" with a many-to-many relationship to some "features" Raku has. So, presumably, when a user thinks "WTF is $thing, WHY and HOW do they use it?" or "WTF is this complex concept of role punning, what are more realistic examples here?", the curious user can go here.
The first section is pointed towards users who want to look up "real world" solutions, second one - to users who want to explore the language itself. Guides like "learn the language in 99 problems" or solving pure math problems are not so popular among newcomers, in my opinion, and so the current structure does not really stand up as was mentioned by Timo.
To go this way, steps are:
- Make this virtual structure into a website design (the designer is available already to do this task)
- Revise examples: categorize, revise cookbook, add tags, specify complexity
- Further adapt the website to provide new look and feel with revised content
If possibly, step 2 will benefit a lot if number of members will be able to help out on some Saturday evening or something like this.
This idea suggests the examples website should not be a wiki-like with nice navigation (as in the first suggestion) code storage, but instead a gradual course (something similar to https://gobyexample.com/ (there is an incomplete Raku port around), but not really a copy-paste) which tours a newcomer over the language.
It is suggested to serve two purposes:
- A new user can go here and gradually go from hello world to extensive usage of cool CORE classes we have
- A new user can go here and look up some syntax for particular language feature
When a new user who is not used to Raku yet (regardless if knows another language or not) wants to look up something like "How do you write an if clause again, with parens or not? Don't really remember what was it", they can go here, look up if/else and that's it.
The complicated part here is Raku not being a simple/compact language and currently there is no writer available to design a complete language course like that above. Still, we can discuss this idea and the resources necessary.
To go this way, steps are:
- Make this virtual structure into a website design (the designer is available already to do this task)
- Write a course, hopefully incorporate some chunk of the already available examples
- Further adapt the website to provide new look and feel with revised content
As I have not done any real Raku marketing nor teaching, I am asking for comments regarding the ideas suggested above. While I can do most of the tech-y work alone and the designer position is set, I would like to be advised on how to create something which will be the most beneficial for Raku community.
Please, comment this gist directly or ping me on #raku freenode channel as sena_kun or Altai-man. Hope we can go without too much bikeshedding, suggesting something completely different thus never implemented, etc.
Ping @JJ @lizmat @moritz
Ping @stmuk @grondilu @shlomif @andreoss