Hello, I’ve been sort of reading up on Elm now and again. I decided to follow through a bit with an actual coding project without giving up…and I did manage to “do something”.
Here is that something–it’s a box in which you can click points and get numbered dots connected by lines…as well as my account of getting there:
It was largely a good experience, and went smoothly once it got going. But I mention some feedback points on the Try Elm examples–in particular the Playground.
From the “Conclusion” way down at the bottom:
Once I got started with it, Elm did not feel hard to grasp. Strangely, the
“easy” examples on the “Try Elm” site were the part that threw me off the
most. Something about their presentation created a barrier to being able to
contextualize just what it was that I was looking at.
I can empathize with why the playground examples are included. They are
actually a fairly sophisticated demonstration of abstracting away application
structure. It’s in a style that would be difficult in many other languages.
But the purple dot example–with no user state and deliberately unused
parameters–really just added confusion for me. The lack of type signatures
and comments turned it into a cryptic puzzle to be solved about advanced
abstraction features, as opposed to an “easy” example for teaching! And
once the puzzle was solved, I found I had to throw it all out…which makes
me feel the Playground is a bad entry point.
I’d be happy to elaborate on this. One concrete suggestion I’d certainly make here is that the samples themselves follow the Elm Style Guide. It mentions type signatures and qualified names. I’d have been able to search much more effectively if game had been called out as Playground.game, for instance. It would also be ideal if the examples were engineered in such a way that they did not need to use <iframe>!
Your confusion about the Playground examples is a result of them not being for you. It must have been quite confusing, like being handed a set of child’s toy tools and wondering how you’re supposed to use them to build a spice rack.
Playground is a tool for using Elm to teach programming to people (particularly children) that don’t know any programming. The lack of type signatures and comments is intentional because they’re meaningless and distracting to the intended audience. It’s not intended to help experienced programmers learn Elm or to be an example of idiomatic Elm code.
A problem with the analogy is that in this case, the children’s tools are shown accomplishing a very common-seeming desire of acting on mouse coordinates. Other examples don’t show it, and the elm-guide does not mention the topic.
Things get murky very fast if you start searching. Some dated examples show using “Signal”, and if you manage to find them it is discouraging to get to that point only to learn that they do not work. Answers that suggest installing user modules require a jump to having Elm locally…which it seems you should not have to do, as Try Elm does not seem to need them.
Given all this…it seems reasonable for someone to have thought they should try adapting the Playground sample. Especially if after skimming the guide they felt they basically “get the idea” and could go back to it with any questions.
Have there been any metrics to suggest the format is working for that audience? Are children searching the internet, finding the demo list, narrowing their focus to the “Playground” section… then drilling down into the examples and modifying them meaningfully?
I’d be skeptical that children would seek pure functional programming in a browser out. But…if they were prodigious enough to be doing so–and able to edit textual code and patient enough to interpret the ensuing errors–they’d be of the bright sort who would benefit as much from comments and context as anyone!
(I don’t know a lot about children. But one thing I have gathered is that when you try to make something for them based on what you think they will be receptive to without letting them be involved in the process and getting their feedback, it never works…)
Actually I don’t think it’s intended to be directly accessed like so by inexperience people, but rather through tutoring. I’ve already used the playground with people that never programmed before and it was fun and engaging. I think your negative experience with it results from your expectations, which are misaligned with the target audience of playground examples.
If someone is looking over your shoulder, I’m sure that can help almost anything! (including advice to avoid trying to get mouse coordinates, or installing certain user modules…)
If phrasing as a single “bug”, I might title it:
Mouse coordinates need elm-guide chapter and/or non-Playground sample on Try Elm.
But I’d also think that moving the Playground to something like playground.elm-lang.org and “branding” it differently than Try Elm could also be helpful. This would allow entry-points to match the intended audiences.
Though I don’t think it would be as much of an issue if the Playground wasn’t seeming to demonstrate a facility that wasn’t covered by a better example.
