Tutorial chapter order

[shaedrich]

When reading the tutorial, even though, I did it in the order, the chapters were provided, it sometimes felt, like I actually read them out of order. Here are a few suggestions that would—at least for me—would feel more intuitive: – Explain literals before classes – Move trust boundary to C-FFI – Move matching to operators

I have a hunch, with that, the number of "we'll explain later" and "we partially already explained this earlier" can be reduced

This might be related to #14

[jemc]

This was discussed on today's Pony sync call.

One by one:

– Explain literals before classes

If we moved the literals page before classes, we'd need to move the entire expressions section. There's kind of a circular dependency here and there's no clear "first this, then that" option. However, we think it makes sense to start with high-level things (the types), and move things into more low level details (expressions). Also, actors are part of what makes Pony special, and so

• Move trust boundary to C-FFI

There are other parts of the Object Capabilities section that refer to the Trust Boundary page saying something like "we'll cover more on that later". Also, this whole section is mostly about security, and so is the Trust Boundary page.

So while this is debatable, we agreed in the call that it should stay in the Object Capabilities section.

– Move matching to operators

There's too much material there to make it part of Operators, and match isn't really an operator.

But we think it would make sense to move "Match Expressions" and "As Operator" (in that order) into the "Expressions" section, between "Control Structures" and "Methods".