make tour assume less understanding of imports

[RyanBrewer317]

I rewrote parts of the first two lessons to make them more friendly to an audience that isn't familiar with modules (like the terms "qualified" and "unqualified" imports). The persona I have in mind is someone hot off their first online coding course in, say, JavaScript. I would love for Gleam to appear accessible and non-scary to them and I believe my additions aren't too lengthy.

[RyanBrewer317]

@lpil thanks for taking the time to review this!

I have a decent amount of experience as an educator for college students with little to no experience coding, and I've been helping my wife learn JavaScript. I thought I'd take a look at the Gleam tour to see how approachable it is for people at that skill level, because it would be really fun to teach my wife Gleam. I was surprised to find that the second lesson (and even a few details about the first) contains a bit of scary terminology without slowly defining it.

Modules as a concept are simple but not as pervasive as you'd think. Many people only know JavaScript or Java, and not even the various complex build systems of JavaScript. Jumping in to a discussion of "qualified" and "unqualified" imports at the very start of the tour seems unnecessarily scary, and might turn people away; it's not in the spirit of our friendly language Gleam. It only took a few extra sentences to validate not already knowing these concepts and to gently bring the reader up to speed.

And lastly, I don't believe these changes make the page as long as you seem to think. Here it is alongside other similar-length pages in the Go tour and Gleam tour. It's the most words of these examples, admittedly, but I only took thirty seconds to look, and visually it appears right at home among these.

[lpil]

That's great, thank you.

The tour assumes prior programming knowledge, and while I really like what you're written here I'm not very convinced that this makes the tour more useful to the majority of the target audience. I worry it'd be a worse tool for getting folks hooked on Gleam. You'll notice the Go page you have screenshotted there has a similar level of assumed jargon that it doesn't explain.

Perhaps there's a middle ground where we can explain more but not go as far. We will need to keep the lesson name the same either way as the tour is linked to from elsewhere.

Many people only know JavaScript or Java...

Just to point out, Gleam has almost exactly the same module system as JavaScript, though slightly simplified. 😁

[RyanBrewer317]

Alright, I'll close this then. It's good to know about the target audience and assumed knowledge. I might go ahead and create some of my own Gleam learning materials at some point, which I'm assuming is okay.

Thanks for your politeness working through this with me :)

[lpil]

I think that would be really cool!

I honestly would love to work on this too. A book that introduces functional programming (or programming in general?) using Gleam would be so wonderful. It could work really well!

Not at all, thank you for being so courteous as I block your very well written contribution.

[lpil]

Hello again @RyanBrewer317 ! I've been mulling this over overnight and the more I read this lesson the more I agree with you! I'm going to incorporate your changes here

[RyanBrewer317]

Oh wow, wonderful! Thank you 😊

[RyanBrewer317]

@lpil it seems there are a couple typos in the new modules lesson:

For example, to import the gleam/io module is referred to as io once imported.

See how the gleam/string module is be referred to as text here.