Learning curve
Closed this issue · 7 comments
First up, this is absolutely excellent (along with your general purescript guide). Thank you so much for putting it online.
I'm not a purescript or halogen beginner, but I have been using your guide to refresh my understanding of halogen and improve the gaps in my purescript. One thing that springs out at me is that like the issues raised in #36 I found when I moved through your examples, I quickly got to the point where I wanted to build an extremely simple real halogen component and start to construct an app with it, and to do that I had to kind of pore through the scaffolding code (very easy to do) and reconstruct the call to mkComponent myself. Not terribly difficult for me to do, but I can't imagine it'd be easy for a beginner, or intermediate.
One thing I find difficult about the halogen docs themselves (and I'm using your docs as surrogate docs) is that the types are huge. I feel like everyone would have said this, so I'm not complaining at all here, it's what you need to have if you want a good component system.
However, the standard component type hardly fits in my short-term memory, and it's positional (ie not using a record). Your scaffolding really makes it a lot easier at first, but it suffers from the problem of it being harder to learn "the real way", if that's what you're after later — so I'm advocating for gradual ramp-up with simple real-world components of increasing complexity.
So I suppose what I'm suggesting is... keep the scaffolding, and also add non-scaffolded versions of each. This would clear it up and make the parent/child communication section a lot clearer, I think, too. I'm suggesting a more gradual ramp-up, both with the training wheels on, and off at the same time, so that when someone is interested in taking the training wheels off, they can go back to the simple examples and try the variants without the training wheels.
(So on the one hand, we've got the complexity level of the examples, which ratches up slowly, and on the other hand we have the "training wheels" (scaffolding), which can be on and off both at the same time, to allow someone to learn with or without independently of the complexity of the examples — naturally certain levels of complexity will only have the traning wheels off, at which point you can say go back to "X" point and learn with the training wheels off now please)
Thank you again so much for writing this, and I'm happy to help if you'd like some help.
Thanks! I'm glad it has helped!
I felt like there is truth to #36 but I wasn't sure what the solution was.
To help me understand you better, could you answer these questions?
- how much did you read before you started to feel that way (e.g. wanting to build a real component and finding the current approach unsatisfactory / something that added unneeded friction to your goal)? Perhaps stated differently, when did you first want to descaffold the scaffolding code?
- how far into the repo have you currently read so far?
However, the standard component type hardly fits in my short-term memory, and it's positional (ie not using a record). Your scaffolding really makes it a lot easier at first, but it suffers from the problem of it being harder to learn "the real way", if that's what you're after later — so I'm advocating for gradual ramp-up with simple real-world components of increasing complexity.
It might help for me to provide some context. The Halogen v4 docs worked exactly like you described above. The first example was a simple toggle button example. It then proceeded to add examples that covered more complicated parts. That's what I used to learn Halogen. However, after learning it, I thought that the approach being top-down quickly overwhelmed a new learner. I proposed a bottom-up approach and submitted a PR that didn't get merged. As time went on and Halogen v5 came out, I decided to port that PR over to this project and update it to v5. I think your comment and the one made in the other issue is highlighting the issues that arise when using this approach.
If I'm reading you correctly, it sounds like you're suggesting that I have both a scaffolded version and non-scaffolded version of each example. Thus, when one is initially learning, they will refer to the scaffolded version. Once they feel competent/confident enough, they can look at a real component that provides a good example without having to go through the mental acrobatics of descaffolding the scaffolding code.
If so, I think that makes sense and seems like a good solution to this problem.
Could you submit a PR where you do this with a very simple example, so we can see how that looks and further discuss issues that might arise with this idea in that PR?
- how much did you read before you started to feel that way (e.g. wanting to build a real component and finding the current approach unsatisfactory / something that added unneeded friction to your goal)? Perhaps stated differently, when did you first want to descaffold the scaffolding code?
Once I got up to the parent/child section, which I found kind of confusing at first because it seems to go from smoothly ramping-up connecting everything to extremely complicated, missing bits, straight away.
- how far into the repo have you currently read so far?
I've read the whole thing (a few times, just to make sure).
If I'm reading you correctly, it sounds like you're suggesting that I have both a scaffolded version and non-scaffolded version of each example. Thus, when one is initially learning, they will refer to the scaffolded version. Once they feel competent/confident enough, they can look at a real component that provides a good example without having to go through the mental acrobatics of descaffolding the scaffolding code.
If so, I think that makes sense and seems like a good solution to this problem.
It might be a good solution. I'm not sure, really. I should really have thought more about the issues I had before commenting. I left it for a few days, but I was quite keen to roll my sleeves up build something complicated, and I thought you might like to know the feedback.
Could you submit a PR where you do this with a very simple example, so we can see how that looks and further discuss issues that might arise with this idea in that PR?
Yes, you've understood what I meant perfectly. I'm working on a PR now.
PR request: #43
You know... looking at the examples in the source for halogen, maybe it's just enough to point people at that when they're at that point? What do you think? It's almost what I'm talking about, except that again, there, they get complicated really fast. I guess what would be great is something like the intro material the reagent library in clojurescript has. Not sure if you've seen it: https://reagent-project.github.io — a bunch of real-ish examples that get progressively more involved, but where it's not pulling any punches, but still small enough, which are explained and you can learn from.
Once I got up to the parent/child section, which I found kind of confusing at first because it seems to go from smoothly ramping-up connecting everything to extremely complicated, missing bits, straight away.
Maybe this is another issue at heart here...?
I've read the whole thing (a few times, just to make sure).
I was quite keen to roll my sleeves up build something complicated, and I thought you might like to know the feedback.
Thanks for answering my question. I was wondering whether you had gotten to the template file yet and was giving this feedback without that knowledge.
And yeah, I appreciate the feedback.
You know... looking at the examples in the source for halogen, maybe it's just enough to point people at that when they're at that point? What do you think? It's almost what I'm talking about, except that again, there, they get complicated really fast.
So, perhaps this repo just needs more "real world" examples that build progressively and use less scaffolding (or inline it) after we hit the parent/child part?
I'm going to look at your PR now.
Yeah that sounds great... (the real world stuff). I added this to the PR, which I'll quote here:
I suppose the core issue I have is that the docs and examples in the docs don't clearly explain what all the pieces are in one place, so your document has this decided advantage of being able to isolate complexity... yet it seems the material has a few gaps, as you point out in #42 — once we've gone through the simple examples, maybe we need a point where they can decide to either continue with more examples and slowly introduce the more tricky/real-world types (for example, adding state, then adding passed-in state (ie
input), then when actions come into the picture) then parents, then children, then passing state between them, then querying, then parents & children components, slowly lifting the training wheels off as we go?
Nice. #45 is great :)