Designing Elixir Systems with OTP: Explain the Quiz application more fully up front before getting too granular

Preface

I’m finding this to be a wonderful book that has taught me a lot so far, and I do understand that the core purpose of the book is to communicate to the reader the main design patterns for OTP in Elixir, and not to hand-hold them through an example application tutorial.

Having said that, the irony of the following isn’t lost on me :slight_smile:

Problem

The app we are building is described in Start with the right data layer > Try it out > Break Nouns into Data Structures:

In our quiz project, we can have templates in various categories that create questions. For an example, a template for a simple addition problem may be <%= left %> + <%= right %> with [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] being valid values for left and right. This means a quiz might generate 3 + 2 or 0 + 0. As we ask questions, we track the user’s responses and we keep generating questions until our user masters the template. Once they get three in a row right, we’ll let them move on to the next category.

Which I found to be abrupt, too shallow and relatively impenetrable. Consequently, I’m finding the Build a Functional Core section quite hard to follow.

For example, where did these nouns spring from? There was no high level explanation allowing you to wonder what nouns you might come up with on your own, or how you might build the app based on your own experience thus far. There was no opportunity to engage with the content - it was just force fed to the reader.

And the app itself - Is it a CLI? A desktop or browser based app? Who is the user? How will they actually use it? Are they typing in arguments and clicking generate? How are these templates generated? Will the app be pre-loaded with templates or are the questions user generated? Is a ‘template’ a Phoenix-style EEx template or just domain language for this application? I’m floating around without any context here.

I feel like the section is focusing so hard on design patterns that it’s neglecting necessary context and the big picture of the application that we’re building. It leaves me copying out the code and filling out the module functions but not understanding why. Is it working? How should I know? If its not working, why not? If Elixir has made breaking changes, how can I tweak my code to get it working if I don’t understand, at a high level, what that code is trying to do?

Suggestion

The reader needs a place to go back to from time to time where a detailed, high level explanation is provided, so they can zoom out from the nitty-gritty and reacquaint themselves with what this all means for the user and for the application as a whole.

Please flesh out the initial explanation of the app in writing. A wire-frame or user flow diagram could be included. Intermittent IEX sessions could be included between code examples to keep us grounded in what we are trying to build (okay, now we’ve written these functions, let’s go into IEX and see what a user can do, and also see both the app and our design pattern in action).

TL;DR

Following along with Build a Functional Core reminds me of unit testing without integration testing but for my brain. Some integration explanation as well as unit explanation please!

4 Likes