Add new concept json and concept exercise githup-api
#694
Conversation
|
The learning objectives in the design document look good, although as you suggested it might be a lot? I suppose this is pretty far in the curriculum so probably it doesn’t matter as much and it’s good to have some meaty exercises? Just to clarify, because I haven’t looked at the platform for quite some time. I should review the concept about.md which will be the first thing students will read? (Or at least a simplified minimized version of that). And then there is the exercise instructions.md ? |
That's what I'm leaning towards. It want people to be able to use JSON decoders after going through this, so we should cover whatever will get them 80% of the way there.
Yes, that's right, the first thing they will see is the instructions (I'm not really planning on minimizing too much other than the last section, because everything is necessary for solving the exercise), then the exercise instructions, along with the hints if they choose to read them. |
|
@mpizenberg @ceddlyburge |
|
Hi @jiegillet , what sort of feedback are you looking for? Should I review this with the plan to approve it? Or do you want more general comments on the approach taken and things like that? |
|
I was thinking a more general one first, since JSON decoders is a pain point for beginners, it's worth thinking about the approach. It's been a while since I opened the PR though, I don't remember the details. If it's too much work, review with the intent of approving is also fine, because it's a bit wasteful to just leave it unreviewed forever. |
There was a problem hiding this comment.
Hi Jie, overall I think this looks great.
about.md is very long, and I think I would not have been able to understand it when I was new to Elm and new to JSON decoding / parsing, its very different to how things are done in most non functional languages.
You have described a lot of the decoders in about.md, which is good, but each decoder doesn't have that much description. I could understand it, but I had to read it pretty carefully, and I already know how to do it! I think it might be better to add more description and examples to some of the simpler decoders, but with examples of combining things together, to really bed in the ideas / concepts. Then just mention the other decoders and what they do, but leave the student to go and look them up when they need to.
Also, are there any common gotchas for new students? I can half remember some frustrations when I was learning, but only half!
A quick search on slack shows up:
Not understanding Decode.map
https://elmlang.slack.com/archives/C0CJ3SBBM/p1723375470463649
Getting confused about json property names and elm record names
https://elmlang.slack.com/archives/C0CJ3SBBM/p1720733981844319
Cheers, Cedd
concepts/json/about.md
Outdated
| --> Err ... | ||
| ``` | ||
|
|
||
| Note that `Decode.list : Decoder a -> Decoder (List a)` and `Decode.dict : Decoder a -> Decoder (Dict String a)` each expect a decoder as argument, which is expected to decode every single element elements of the data structure. |
There was a problem hiding this comment.
Might be worth talking about combining decoders here? People get excited about combinators, and they are powerful, but they aren't as mysterious as people think!
There was a problem hiding this comment.
I split the section in two (core data types / collections) to facilitate that.
What would you talk about specifically?
(sorry for the 3 month response time, I finally have some time to focus on this PR this week)
There was a problem hiding this comment.
Looks good, its a complicated topic, and a long document, but worth it I think ...
There was a problem hiding this comment.
Do you think it would be better if I straight up removed the references to to GeoJSON and simply described the different decoder functions?
One one hand, I liked the GeoJSON thing because it's real world, but on the other, you're right that it makes the document very long.
One thing I could do it keep it for the about document but remove it from the intro, and I would just introduce the different functions there.
|
It does make it long,, and it requires the student to understand both the geojson API and the GitHub api to do the exercise. But examples do make things easier to understand. Maybe use the github API instead of the geojson? Then students only have to understand that one? |
We can't show the answers of the concept exercise in the introduction, that would make the exercise meaningless.
Then let's publish as it is and see if we get feedback? That's what the "beta" status is about. |
|
I was thinking that you could pick out bits that might help the solution,but not be the solution. I'm happy to merge it and await feedback though :) |
Closes #538
@ceddlyburge, @mpizenberg I would love to have notes from both of you on this one, since it's one of those tricky topics for beginners. I'm not convinced I took the best approach, so any feedback is welcome. There is no hurry, let's take our time and get it right.
For the concept exercise, as we discussed on the issue, I took the approach of writing decoders for a real-life GitHub API. Not all fields are included of course, but the ones that are mentioned and their specs are real, which felt nice.
For the concept introduction, I tool the approach of decoding GeoJSON, which got me excited at first because it's another real use case, but now I wonder if it wasn't too complex.
Configlet on CI fails, which is expected, it will keep failing until we finalize the intro and I copy it in the exercise.