CSS issue in Ember Guides

[Devashish0210]

Stage	Start Date	Release Date	Release Versions		Relevant Team(s)	RFC PR
Accepted	28/07/2021	Unreleased	ember-source	ember-data	Ember Learning Team
----------	-------------	------------	v3.26.1	v3.26.1	------------

Summary

This feature will create a copy of the CSS file on our device at the time of running the command "ember new super-rentals"

Motivation

To add simplicity to the guides.

Detailed design

In the current version of the Ember guides, there is only one CSS file that serves the purpose of decorating our Super Rentals Ember app. This CSS file has to be downloaded separately through a link which is given to us in the guides.

The issue that I have faced recently while following the guides is that I had accidentally skipped the download link for the CSS file since it is not defined under a broad CSS heading (it is just a simple paragraph containing text and a link). When I could see visible changes in the expected output given in the guides and the output I was getting on my localhost, I knew the exact root cause of my issue(missing CSS file) because I have worked with a few guides before. So I immediately scanned the Guides thoroughly and found the link that I had missed and downloaded the file. A new user might not know the cause of the issue and if for instance a new user faces an issue similar to mine, the user is likely to be disheartened and skip the guides completely.

The CSS file is majorly responsible for making any webpage/app look attractive. Therefore, if a user does not download the CSS file, they will see a huge difference in the app generated by their system versus the screenshots of the expected output in the guides.

How we teach this

To fix this issue, I would suggest the following steps -

• 1. At certain relevant points throughout the Ember Guides, we can add the CSS code for the users to copy into the CSS file. Basically, teaching the user how to do CSS.
• 2. The main problem with Solution 1 mentioned above is that we are working on Ember Guides and not CSS Guides, so teaching the user how to do CSS is not out prerogative. Hence we can temporarily have a small dynamic sub-heading called "CSS" (I am not the best at naming things, apologies) that contains the link so that even the most dumbest of users cannot miss it.
• 3. As mentioned above, Solution 2 is just a temporary fix to the problem. To fix the problem of the missing CSS file once and for all, we can make it so that when the user creates a new Ember app by running "ember new super-rentals" on their terminal, Ember automatically loads the CSS file onto their device. This way, we can skip telling the user anything about the CSS file at all since it all happens right at the time of creation of the app.

Presto! Problem Solved

Drawbacks

Alternatives

Unresolved questions

[jenweber]

Thanks for writing this up! I like the idea of having a new tutorial page for styles/CSS. It's great that we can do that work right away while we tackle the more difficult question of adding this to the CLI. We'll talk about it at today's learning team meeting. The article content would go in this repo: https://github.com/ember-learn/super-rentals-tutorial/ and the new page would also need to be added here: https://github.com/ember-learn/guides-source/blob/master/guides/release/pages.yml

I have a couple suggestions -

For motivation, I would add something like "To improve the experience of developers going through the super rentals tutorial. The CSS step is easy to miss, and if we make CSS more prominent, we can create a new learning opportunity."

If you want some more naming ideas, we could call the new tutorial section "Styling." We try to name our Guides topics after the general concepts instead of the specific technology used.

Some gentler words here: "...that contains the link so that all users can find it easily".

[jenweber]

Notes from learning team meeting:

• The new page would go right after Orientation
• Devashish is working on a blueprint for generating the files. This will take a lot of time. A little stuck on this. @mansona might be able to help!
• It's not documented how to achieve blueprints for addons - this could be improved in the CLI guides
• Adding a new page can move forward!

Next steps:

• Open a separate issue in the Guides and tutorial repo for adding the new page
• Devashish will write the page. @jenweber is happy to help review!

[chancancode]

@Devashish0210 I emphasize with your problem and you're definitely not the first person to run into it, in fact there is an open issue about a similar thing in the tutorial repo. I think we need to fix this, but here are some things to consider to help find the right fix for this. I'll frame them in the context of your three suggestions.

1. At certain relevant points throughout the Ember Guides, we can add the CSS code for the users to copy into the CSS file. Basically, teaching the user how to do CSS.

This is not a bad idea, and it's similar to how we approach testing, for example. However, as you have already pointed out, the goal of the tutorial is primarily to teach Ember, so the more stuff we add that is not directly related to Ember itself, the more it distracts from that goal.

• For readers who are already familiar with CSS, it adds more noise for them to skim/skip through, which causes them to miss other important things (which is, ironically, what causes this issue to be opened in the first place).

• For those who are not already familiar with CSS, it's an extra concept that we are forcing them to grasp and understand inline, when they are already learning so many other new things at once, when it is otherwise an independent thing that could be layered on after (and we can point them to resources at the appropriate places if we think they are hard to find).

Overall, if we expand the scope too much, it makes the tutorial more comprehensive, but at the expense of losing focus and making it takes longer to go through. At some point it contributes to the notions like "Ember is hard to learn", or "you need to be proficient with HTML/CSS/JavaScript before you can even attempt to learn Ember", etc, all of which we are emotions we were trying to avoid.

Granted, different people have different learning styles, and one could make an argument in the other direction. Some may prefer that this to be a complete guide to programming for the web, from start to finish, while some may skim through the tutorial as a "taste test" for Ember. IMO the current approach strikes a good balance of taking care of most people's needs, on balance. We are not really hiding anything from the reader, so you could definitely go look at the CSS, learn more about it, tweak and experiment with it, but for those who don't immediately care to do that they can move right along. I think this is an important goal to preserve.

2. The main problem with Solution 1 mentioned above is that we are working on Ember Guides and not CSS Guides, so teaching the user how to do CSS is not out prerogative. Hence we can temporarily have a small dynamic sub-heading called "CSS" (I am not the best at naming things, apologies) that contains the link so that even the most dumbest of users cannot miss it.

While teaching how CSS works, per se, is not the goal here, teaching how to work with CSS in the context of Ember app (i.e. where they should be placed, how to edit them, do you have to refresh the page to see the changes, etc) is definitely an important goal for this section.

I agree the current text is easy to miss if you were skimming (and as the issue pointed out the /* ...snip... */ comment could also be confusing ), and a more prominent callout would be good. We have visual aids like "Zoey Says..." to help with these kind of things. Also happy to stylize it as a button, etc.

As far as breaking that into a separate page, I think that would be an overkill. I am not totally opposed to breaking up the current section into three sections – one for HTML, one for CSS and one for assets.

However, I am not sure that would really help that much and seems to interrupt the flow of the current content IMO. Can you elaborate on why you think that would help and flesh out a bit on what extra content that section should contain?

When working through these kind of issues (roughly: "X was too confusing/too easy to miss"), it's important that we take the time to dig into the root cause and address it that way, as opposed to scenario-solving. If we bold everything that someone missed at one point then everything would be bolded, and if we add a "Zoey says..." for every question that anyone had in the past, then each chapter would be 10 times as long. Too much information could be a bad thing, especially since this issue is at least about existing information that got lost.

Again I agree this spot definitely could use improvements, I just wanted the fix to be targeted and precise and that we don't overdo it, as it will come at the expense of something else, and everything here is a balancing act. Personally, I don't think it's a good idea to make the reader sit through another chapter or long section that explains CSS in details before they get to the more exciting parts that they are ultimately here for.

3. As mentioned above, Solution 2 is just a temporary fix to the problem. To fix the problem of the missing CSS file once and for all, we can make it so that when the user creates a new Ember app by running "ember new super-rentals" on their terminal, Ember automatically loads the CSS file onto their device. This way, we can skip telling the user anything about the CSS file at all since it all happens right at the time of creation of the app.

We used to have something similar, in that the tutorial asked the reader to install an add-on that supplied some styles/blueprints/components. IMO, this is a bad idea. The teaching goal in this chapter is to help the reader understand where you would put CSS files in an Ember app, not just that "here are the opaque boilerplate and magic incantation that you need to do to bootstrap the tutorial.

While some kind of automation here will marginally speed things up for the reader, it comes at the expense of:

1. Not explaining the structure/anatomy of the generated app
2. You would have no idea how to do the same thing in your own app
3. Front-load other concepts like "generators" (currently chapter 4) and "addons" (currently not in the tutorial, but should get a chapter at the end)
4. Contributes to making Ember/the tutorial feel like "too much magic"

The current setup prioritizes drawing parallels to how you would otherwise do things in a "standard" web development setup outside of the Ember context, and therefore teaches manual file creation upfront, and only move to generators as a convince later on once the basics has been established. This is partly to show that you can do it (there are no extra magic involved in the generators, it just automate some manual steps that you could have easily perform yourself), but also to take care to not introduce too many concepts at once and instead rely on and related to priori experience the reader would have had from other context (manipulation of files in the operating system).

So I think any solution that involves generators and addons and automations this early on would defeat this goal.

[jenweber]

Hi all, thanks for sharing your thoughts. Maybe we should find some next steps are that we can all agree on, we do those first, and then see where that takes us. The learning team had agreement on the plan laid out by @Devashish0210 but I think it's good to iterate. The CLI changes would require a real RFC, so I don't think we need to make decisions for that yet.

I suggest we begin with revising the existing CSS section to be more prominent. For example, we could add a heading:

### Add some CSS to your app

Before we do anything else, let's add some styling to our app. We spend enough time staring at the computer screen as it is, so we must protect our eyesight against unstyled markup!

...

Similarly, another subheading could be:

### Check that your new styles are working

When you are ready, save the CSS file; our trusty development server should pick it up and refresh our page right away. No more unstyled content!

<IMAGE >

Your app should look something like this before you move on to the next step.

And then to label the image CSS work, we could have:

### Add an image

To match the mockup from our designer, we will also need to download the teaching-tomster.png image, which was referenced from our CSS file...

[jenweber]

Edit - one other thing I want to add is that if we were to make it a new page, what we discussed in the meeting is that it would be very short and sweet, and not aim to teach CSS. The information density would be similar to its current form.

[jenweber]

Another idea from the learning team meeting, from @mansona, is to add a Zoey says on the next page of the tutorial, "By the way, if your app doesn't look like this, you might have missed the Add the CSS section."

One question for you @Devashish0210, at what point in going through the tutorial did you notice you were missing CSS? That may be a good place to put the Zoey says callout.

[jenweber]

@Devashish0210 let me know if you would like to do some pair programming for any of these next steps. Thank you!