📖 Elm in Action: the good and the bad

[badlydrawnrob]

TL;DR

This needs writing better, with some actionable bullet points for teaching to a beginner or intermediate level.

As a chapter becomes more complex, it gets harder to create Anki Cards.

It isn't easy to write a coding book.
⭐ Errata can make it difficult for student.¹
Slowly step up from atoms to blocks.
Refactor as you go (with explanations!)
Break it down to the ridiculous.
Be concise, just enough and no more.

Style

In many ways the PDF version is better presented and styled. I guess ePub has some limitations on formatting pg.116 (pdf) and pg. 278 (epub) are good examples of this.

It's not so easy to explain

Part 3: Building Bigger is especially confusing. Recursive Types and the more difficult aspects of json and routing is a very hard thing to explain. I find, the more code in the file, the hard it is to follow what everything is doing.

Elm and functional programming is quite a bit harder to teach than basic Racket stuff; a lot harder to teach than Scratch. There's just a lot to learn and it's going to take quite some time (2 years) to fully bed into your memory and muscle memory. The basic teaching packs are probably a very wise thing to keep syntax to a minimum, and learning without types takes some of the sting out too.

• 170 research papers on teaching programming
• Why it's hard to teach programming

I guess part of the problem teaching this stuff is you need a ok memory of the meta. The terminology, the lingo, knowing the difference between a Type, a Custom Type, Type alias and Type variable. And so on.

⭐ Knowing where to start (teaching)

And when to introduce key concepts

The PhotoGroove app is quite iterative.
A story could be also. Start basic and small ...
Add characters, colours, and context.

The code sample below requires (at least) 3 full chapters to get to.

To be able to understand this:

aCustomTypeVariant : Int -> Float  -- #1
aCustomTypeVariant index =
  case Array.get index numberArray of
    Just age ->                         -- #2
      age
    Nothing ->
      0

First requires you to know:

1. How to write a function (a full chapter of it's own!)
2. How to think about Type annotations (a full chapter of it's own!)²
3. What the fuck is a Maybe?
4. How do I deconstruct a ...
   • (start with a function with (x, y, z) tuple)
5. What is a case statement?
6. What is an Array, and how to I convert from a [] list?
7. When should I use a list, and when an array?
8. Finally, breaking down Just and Nothing (use the elm repl)
9. Now I know what they are, I can write the function.

When starting to introduce difficult concepts ...

Start with the absolute basics.

For instance, a HTTP get request could be as simple as:

{
    "A json string" : "[\"Ford\", \"BMW\", \"Fiat\"]"
    "A json array" :  ["Ford", "BMW", "Fiat"]
}

"One of our helpful coworkers has set up a simple server endpoint that returns a comma-separated list of photo filenames. The list doesn’t yet contain the metadata that we’ll ultimately need, but it’ll give us a good starting point toward that goal. Let’s send an HTTP GET request to fetch that comma-separated string from a server."

Obviously things would need to get a lot more complicated from here. That's the difficult thing about trying to teach generic programming — once the safety wheels are off, you're on your own to problem solve. The code starts to get more interwoven and complex. That's difficult without a mentor to support.

1. Parse a txt string
2. Parse a single atom: decodeString bool
3. Parse a list of atoms: decodeString list bool
4. Parse a key: value pair: field "email" string
5. Decoding many fields (linking it all together)

The obvious stuff ... errors

Errors are easily missed when compiling a book.
Poor wording or errors can leave a student stuck!
There were a raft of errors in the forums (many fixed I guess)

• Code errata i.e: missing a <span> or Loading -> status thought is wrong.
• A breaking error is worse (code won't compile or view)
  • For instance, function name different to previous chapter
  • String points to an invalid url
• A small typo can cause confusion. Do I need to add a variable here or not? (pg. 194, or pdf pg. 76)
• Not specifying an import like the Random.Generator Int example (it won't work without)
  • It also doesn't specifiy in the book that YOU HAVE TO INSTALL THE PACKAGE FIRST!!³
  • You also need a community (and Elm's is small) to answer certain questions. How to I make it truly random?
• Making sure Elm Lang version is up-to-date
  • Some languages (and therefore books) become outdated FAST.

Searching the book

Highlighting elements with Books app in MacOS
is somewhat helpful, but finding an exact piece of
code that was instructed in an earlier segment of the book
can be quite tricky to find.

Are there better ways to scan through an eBook?

• Generating a Notes.elm for each chapter
• Creating your own mini documentation
• A succinct overview of each chapter

All of the above are quite time-consuming, but the highlights in the book are almost useless in the grand scheme of things. Ideally you need to have a brief context and concrete examples of each learning point.

There's a lot of learning points in this book.

The longer the code is ...

The harder it is to annotate.
See pdf pages 85—88.
See page 216+ for eBook.
Notes are inline with the pdf
Notes are after the code in the eBook

Is there a best of both worlds?

You have to read the full chunk of code (which lasts for 6 pages in the eBook) with numbered annotations then read the list of "what we achieved". Probably better to have a link to a file with annotations in-place, or do what HTDP does and have links to further documentation from each code snippet.

Either way it's quite hard to cross-reference bits of the code to see what they do in book form.

Refactoring as you go

From this ...

randomPhotoPicker : Random.Generator Int
randomPhotoPicker =
  Random.int 0 2  -- This is hardcoded

To this ...

randomPhotoPicker : Random.Generator Int
randomPhotoPicker =
  Random.int 0 (Array.length photoArray - 1). -- This gets the actual length of the list (better)

Other examples

Another great example is reducing a nested case statement with pattern matching.

It gets quite tough (and explaining things does too!)

For instance, starting to use Commands and Flags and Subscriptions and so on (that comes later in chapter 5) but a simple thing like this type annotation:

main : Program () Model Msg

It takes a good few paragraphs to explain, and will come into focus later when we start using Flags. But stuff like this that the learner has never seen before start to get confusing. For instance, I now have about 28 bloody questions that need condensing into Anki cards, somehow. And there's just too much code on each segment that's interleaved with other code which makes Anki cards harder to write!!!

Knowing when to revise, and when to wait til another chapter (it'll come back around) is a bit unclear.

The chapters go into quite a lot of detail about specific syntax, functions, types, and gotchas (especially some differences between Elm and Javascipt). You can safely skip the javascript bits as out-of-scope (just go learn it with another resource).

Especially type alias and custom types take quite a thorough walkthrough, starting out with a simple "String" and moving towards a more complicated function and Union type. The text could probably be reduced if you have some decent sketches or visuals.

How does Richard step you through the process

Go over your commits (from here to here) and see how he steps you through the process.

I suppose you really have to assume ignorance for all things. Take it to the ridiculous ... like, "what is a variable?" is the atom/colour to start from, and build up with blocks.

Footnotes

1. There are quite a lot of small errors in this book. It was updated and added to incrementally so it's to be expected. Perhaps smaller stories result in less errors. Some of the code examples are quite long. ↩

2. Types and Custom Types, especially when it comes to Maybe, Just and Nothing are quite hard to wrap your head around in terms of vocabulary. They're not too difficult to understand but ask me in a week and I couldn't tell you the names of these things. The meta of the language (like grammar terminology in language). ↩

3. He actually does, but not until he's actually introduced the function and explained how it works. Might be better to do that the other way around. ↩