Suggestion: tutorial should start from scratch

[1player]

Origami seems quite interesting though it has a lot of unfamiliar syntax and concepts to learn. To keep it simple, I started with a simple site.ori file:

{
  index.html = "Hello"
}

as it was shown at the top of the Hello, World page and I have no idea how to proceed from there.

The tutorial asks me to clone a pre-made repository with a lot of stuff in it, while there is not even a mention of how to install origami in the first place. By reading the package.json file of the language-intro repo, I ran npm i @weborigami/origami and saw that to run the project it uses the following incantation ori serve watch src, =debug src/site.ori

Alright. I originally ran npx ori to understand what those options do, and:

• serve isn't shown among the list of supported commands.
• the ori help:<namespace> syntax is very unfamiliar to those used to working on CLI tools, expecting to use either cmd help subcommand or cmd subcommand --help
• ori help:serve shows it's a function that takes (tree, port) arguments, so I'm not sure what ori serve watch src means. Is watch passed as the tree argument? Again, unfamiliar syntax and concepts.
• The second part of the incantation , =debug src/site.ori is even more alien to me.

At this point, I am completely lost and thought I'd try to write an issue to present the perspective of a new user, so you have a point of reference on which direction to improve the docs. I know my way around the shell or npm or even esoteric languages, but the approach I prefer is to start small, simple and from knowledge I already have. I could force my way to blindly follow the guide and hope it eventually clicks and all makes sense, but until that happens, one is a bit lost and confused, rather than in a state of productive flow.

IMO the tutorial should tell how to start from scratch (i.e. empty npm repo) to end up with what's in the language-intro repo, rather than using that repo as a starting point. And ideally the CLI tool should work like everything else in the node or UNIX world, with simple subcommands, rather than unfamiliar syntax than somehow maps to function invocations.

Hope this helps and is constructive!

[JanMiksovsky]

Many thanks for the feedback — it’s invaluable to hear someone’s experience looking at the project. That’s especially true when someone has a negative experience; most people in this situation would just walk away.

There are a bundle of issues here; let’s see if I can unpack them.

Tutorial

The core issue is probably that it’s impossible to have a single tutorial for the range of people for whom I think Origami will be interesting.

• At the beginner end of the spectrum, I want Origami to be useful to people who know HTML and CSS and not much more than that. The current language tutorial was actually designed for use on Glitch, a browser-hosted environment that was great for people new to web development. Among other things, Glitch automatically did an npm install and npm start; the tutorial user never saw those commands. Unfortunately, Glitch has atrophied to the point where it can no longer run a supported version of Node. In desperation, I recently edited the tutorial to use GitHub Codespaces, which is not a great middle ground: it’s too hard for a newcomer but advanced devs like you will want to run on their own machine.
• I also think Origami is interesting to experienced devs. For those devs, I have a separate pattern tutorial that starts from zero (no dependencies), but that’s actually too fundamental for someone who’s primarily interested in understanding Origami overall.

Based on your feedback, it seems reasonable to create a separate tutorial for devs that want to see what Origami can do as quickly as possible while still starting from a clean project (without “a lot of stuff”).

CLI feedback

By design the ori CLI is an expression evaluator, interpreting its arguments as an Origami expression. (I appreciate that that is unconventional and unexpected; there’s actually an entirely separate CLI tutorial just to introduce using Origami via the CLI.)

Given that, it’s not feasible for ori to support the expected help conventions. In this regard, it’s like expr or similar calculator commands; the trade-off for being able to type expr 1 + 1 is not being able to type expr help or expr --help. In the long run, I believe that having a full expression evaluator in the shell is worth the initial confusion of not having help via standard means.

The npm run incantation

For better or for worse people trying Origami so far have ignored or glossed over the syntax of npm start/run commands and, presumably, accepted that the commands will do what’s necessary. But it is completely reasonable to ask how they do what they do, and I should document that somewhere.

For now, here’s how the ori serve watch src, =debug src/site.ori incantation works:

• The purpose of the incantation is to serve the site.ori file locally, reloading the file if it or anything else in the src folder changes.
• The expression omits parentheses to avoid needing to quote them, but making the parentheses explicit reveals the function call structure.
• The = is a shorthand for a function call () =>
• So the incantation can be rewritten ori "serve(watch(src, () => debug(src/site.ori)))"
• The debug part wraps the src/site.ori tree in one that will have various values of interest while debugging.
• The watch function will monitor the initial src folder argument for changes. The result of the watch call is a tree that delegates calls to the result of calling the second argument (the function) — with the additional behavior that, if anything changes in the monitored folder, the function will be re-evaluated to get a new tree; the initial tree watch returned will now delegate calls to the new tree.
• The serve function serves the result of watch, which in turn is the tree in the latest site.ori plus debugging features.

Creating a new tutorial is a colossal amount of work. In the meantime, I’ll consider what I can do to better accommodate someone like you.

For example, I’d only envisioned people cloning the language-intro project in the context of the tutorial, so that project doesn’t have an interesting ReadMe. I can look into creating a better ReadMe that explains the need to use npm install, explains how to start and build the project, and summarizes how the npm scripts work.

[JanMiksovsky]

For now, added some instructions for running locally to the language-intro ReadMe