While learning Elm basics by writing an app, I put together notes about where Elm FP’s approach differed from imperative languages I had used.
I’ve written up those notes and ask, could this page be a positive addition to https://guide.elm-lang.org/?
New page:
Hello,
you say:
Without variables the number of states an Elm program can have is greatly reduced, making testing far easier than imperative languages.
and I was wondering how that statement follows from the immutability mentioned.
I’ll assume that with state you are referring to the model of TEA application right?
If so then the number of different, representable states is the same you’d have with an imperative program using the same representation of your model.
Can you say a bit more about what your context was here? Maybe we can help you clarify this.
Hey @Carl 
My initial reaction is that this feels like a harder introduction page than what the current guide has.
This is a lot of information for someone to take on. If someone reads sentences like “there are no variables, only constants” or “an Elm function returns the exact same output given the same input”, they will start thinking about what the consequences of those are and it will be distracting to the rest of their reading (even if you explain it perfectly right after).
I think it’s best to explain these concepts as you go along in the guide, which I think the current guide does quite well.
There’s another point that people who come from all these languages tend to value flexibility quite a lot, and telling them right away “you can’t have variables” may be a big turn-off. Instead, what you could do in a guide is doing something like “here is how you make a web application in Elm?”, let them do it, then “by the way, did you notice how we didn’t have to mutate variables? This is nice because this means ”.
As Elm developers who have been convinced of the nice benefits of the language’s design, I agree with what you say. But developers coming from those languages probably don’t value the same things. They don’t care about immutability, pure functions, etc., because they don’t know them well and they don’t see their benefits. What probably matters more to them are the things that they currently think matters most. That might be performance, ease of writing, coding style, etc. I don’t think you’re going to entice people to dig into the language with what you write. Rather the main points on the https://elm-lang.org/ frontpage are probably the features that will make these developers curious.
I feel like it would make more sense to have your writing on https://elm-lang.org/ rather than in the guide, but an entirely separate blog post would probably be a better fit. If you do a good job, then others will link and refer to it to newcomers.
Without variables, Elm also forgoes primitive loop control flows such as for and while . Instead, Elm has data structures such as lists and functions to manipulate the data stored.
I think you mean to say that Elm uses recursion as a control flow. Probably not a thing to highlight on the first page of the guide, as some people get intimidated by the concept.
In general, I recommend against using the terms “just” and “simple/simply” (and similarly, “easy”), as things that seem logicial/simple for one person may not feel that way for others. If I read something that says “X is simple” and I don’t find it X, I will feel stupid or in some way alienated by the text. Not using the terms helps with people feeling that way.
“but then it dawns on you”
You’re trying to force an epiphany onto the reader. That doesn’t work well. Explain the thing you’re trying to explain, don’t
“you’ll find that liberating”
People don’t like to be told how to feel, especially for something that might feel like an empty promise. Explain the reasons why you think it is liberating. “It helps me by not requiring me to think about transitions”, “I don’t have to think about edges cases” or things like that (adapt to your preferred usage of “I” versus “you” or “we” or something else).
Thanks, @Carsten_Konig - I agree that the sentence “Without variables…” is too vague and needs improving (or removing).
This reads more like a marketing statement, but do you think the following is clearer?
Rather than the model data of TEA, I was referring to how functions are implemented. Using variables in programs often increases the number of states the program has. Without variables, code is easier to read, trace, and cache and since the state of values can’t change code is easier to test, debug and refactor.
thank you, @jfmengels
I think your initial reaction is correct. I should have included an introduction to identify whom these notes were aimed at. The fact it needs qualifying might suggest the page doesn’t belong in this guide. Or, perhaps, not placed so high up in the page order?
I’d like to descruibe how I came to Elm. I was looking for an FP language to learn wihich enabled easy deployment of programs. I knew Elm was different from imperative languages but was vague on the details. Having a page like this would have helped me with some of the fundamentals.
This page wasn’t aimed at enticement but illumination. Though I wouldn’t want to slow Elm’s adoption rate. You suggest I post this page somewhere else. It doesn’t belong if no one (other than me) thinks it belongs.
Your writing tips
Thank you, regarding just/simple/simply/easy.
And on my “epiphany forcing”
I’d avoided writing in the first person (“I”) because the introductory and core languages pages hadn’t used it. However, it is used later on and I’d missed that. That would make the page read much better.
I’d argue that a blog post or such would be fantastic. Reading about other people’s experiences, what excited them and what them stumbled over, is, I think, what being a community and teaching is all about. I read guides and documentation when I need to know the technical details of how to use something, but I read blogs and personal anecdotes when I need to get a sense of the emotional “why” I’d want to use something. The things that are hard to grasp in guides and technical docs.
If you wrote about your journey into learning Elm, and other things, I for one would read it.
Entire text feels targeted not as much at beginners, but rather at experienced developers with imperative habits. Thus title (#) is slightly misleading, I think the subtitle (##) is much better reflecting what to expect from reading. Moreover explanations how to apply your previous experience contain some quite advanced concepts for people who are really new and might confuse them more than necessary.
thanks, @stiff. I think you’ve nailed it. I am a experienced developer with a background in imperative habits. As suggested by @jfmengels and @wolfadex, I’m writing a blog entry to sit next to the app.
Acting upon the feedback in this thread (thanks all) I’ve added a separate post about my early experiences with Elm.
http://9birthdays.com/trying-elm.html
This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.