feat: re-structure the JS course so that it's a flat list of numbered lessons

[honzajavorek]

This is just one of the steps towards completing #1550

Some of the texts may not make sense now, because they talk about sections within the course. It's at many places, so I didn't touch any of that to keep this PR minimal. I only edited titles to mimic the old structure, so the reader may still have a sense of sections.

I also don't consider the titles to be the best possible, but that's for later as well. I plan to read through all the course and fix what can be fixed, so any discrepancies should be just temporary.

Click for instant enlightenment

[B4nan]

Huh, do we really want this? I like the current form with nesting better to be honest. Are you sure you are not reading that "zen of python" too much in between the lines? Isn't it about code rather than docs?

[honzajavorek]

The Zen of Python is there more as an easter egg. I should have provided a real explanation.

I'm of an opinion that courses should be a flat series of numbered lessons, where the only structure is prev & next. It makes orientation straightforward and I immediately know where I am, what is ahead, what is my progress, etc.

This is a first step in revamp of the JS course, which I'm supposed to do now, as the Python one is done. I want to first flatten it like this, and then make changes which will gradually make the sectioning disappear, and fix up the lessons so that they're more standalone and single topic oriented, similar to the ones in the Python course.

If possible, I'd also lower their number, as their amount is probably also a factor contributing to the need of sectioning.

So yes, I agree the result of this PR is not exactly the most appalling, but it's a temporary step towards a more polished course.

[B4nan]

I'm of an opinion that courses should be a flat series of numbered lessons, where the only structure is prev & next. It makes orientation straightforward and I immediately know where I am, what is ahead, what is my progress, etc.

But we have that even with the current structure, next page of the last nested item points to the first item in the next "nested list".

I don't want to block this anyhow, but IMO it's better to keep what we have instead of doing this. I'll let others decide, if this has been already discussed and agreed upon, feel free to ignore me 🙃

[honzajavorek]

But we have that even with the current structure, next page of the last nested item points to the first item in the next "nested list".

I know, technically it works. What I'm after is the mental model and overview of the reader. Which I've been myself, when I started in Apify, and the nesting was both confusing and overwhelming, because looking at the ToC I had no idea where I am regarding my progress, how many lessons I'm in and how many lessons is left.

[B4nan]

I guess it depends on personal preferences, to me the nesting adds to clarity, since it groups what belongs together, and unless you open all the categories as you did in that screenshot, you only see what's relevant to the current tutorial. But if we keep the titles are they are in your screenshot, it's not far away from that.

[honzajavorek]

The goal, in long term, would be to get closer to something like this:

[TC-MO]

I get the goal in the long term and generally I concur, but do we want to make the experience worse in the short term ? (also those are some nebulous terms, short term can be a day or two or a month or two ¯_(ツ)_/¯ )

[honzajavorek]

Is it so much worse? I consider the orientation better. The next step would be improvement of the titles and making the lessons more standalone. But yes, with my part-time commitment, this can take a month or two.

If this is a concern, I can stack my next changes on top of this PR, but then it's gonna be rebasing hell if meanwhile master changes significantly.

[metalwarrior665]

I don't have a strong opinion on this. Do you plan to do something similar with the other courses? For me nested structure makes sense if:

1. There are more articles than X (could be 10 or 15)
2. The subsections also make sense in isolation so they don't necessarily need to follow each other.

In our case, both of these are kinda borderline but the course sections probably follow each other

[honzajavorek]

I'd say sections could be something akin to a code smell. Not wrong, but pointing at something which could be improved. If there are more articles than 10 or 15, perhaps there should be less articles, i.e. the course should be shorter so that it's easier to grasp and finish, or it should be two separate courses, etc. If the sections make sense in isolation, perhaps they should be separate courses, or perhaps they're something more like a shorter, standalone tutorial, which shouldn't be called a course at all.

In the particular case of the JS course, I think the sections are not necessary, and I demonstrated it with the Python course, which follows a very similar arc of narration, teaching similar stuff, but with fewer lessons and without sections.

I do plan to remove content from the JS course and make it shorter. E.g. we agreed that it was written with non-coding beginners in mind, but that's not the bar of the target audience we want to cater to. In the Python course, we define minimal requirements, i.e. that yes, the course is for beginners, but having at least some coding basics is a necessity. I'll do this for the JS course as well and I'll be able remove several pages immediately.

If this is something you think I should be doing before we flatten the course, it'll make my work harder, but ok :) I don't have a strong opinion that the order of steps I'm taking is the best, but I'm of a strong opinion that these things should be eventually done.

[honzajavorek]

I'm putting this on hold for now to explore alternative approaches.