Following up on our meeting regarding a dictionary/reference feature

Is your feature request related to a problem? Please describe.

Currently, users don’t have a good way to review new words or concepts that they’ve learned throughout the course. This is especially true with the new course style that is broken into steps.

Words such as invoke or boilerplate should ideally be defined the first time they are mentioned, but even then there are a couple of problems that lead to the need for a dictionary/reference feature:

1. A user may forget the meaning or a word/keyword. This is especially true if they take a break from the course and come back a few weeks or months later.
2. A user may rush through the step and not take the time to understand the definition in the first place, even if they do quickly read all of the text in the lesson they may not let it sink in. This isn’t even a case of rushing. It’s pretty easy to pass a step without understanding 100% of what it’s supposed to teach.

Describe the solution you’d like

There are a number of solutions to this problem, and I believe that the best way to solve it is a combination of all 3 of the following:

1. Make sure that we always define a technical word first time it comes up. It would be nice from a UX perspective to have formatting on this definition too so that it’s very clear that a new word is being introduced to the user.
2. Add tags to steps that contain the concepts discussed/tested. This way if the user has trouble they can go back and review. This would also enable a search feature later on if we want to add it.
3. Add titles to the steps in the new course format. In the old format, a lesson would have a title such as “Comment your HTML”. Those are useful when I get it wants to review a concept they’re unsure of.

Describe alternatives you’ve considered

After the above three solutions have been implemented, I have a proposal for a definition feature that I think could be subtle yet helpful for users.

This was just a really basic demo that I cooked up, an important part of the feature that would also be there is a checkbox icon in the lower right part of the popup. If you click on it you’ve “learned” the word and the underline wouldn’t show up again. If you’re not logged in you would be prompted to login first, which would be a good way to encourage people to create an account.

I think the main argument for this additional feature is that after all of the three above solutions have been implemented, there are still a lot of users who will have inadequate understandings of technical words. In my experience, if a user feels unsure about a word or maybe doesn’t know it at all, instead of taking the time to click on the associated tag and go back to where it was defined, a lot of them will just live with the cognitive dissonance. It’s irrational behavior, but to some extent they probably don’t realize how detrimental it can be to their understanding. If they have trouble when they’re reading a lesson where they don’t understand a word, we might expect them to try to find the definition but from personal experience the sentiment is not so much “I don’t understand this lesson because I don’t understand this word” but more simply “I don’t understand this lesson, it’s confusing” or maybe just “I’m dumb and I don’t understand this”.

I say personal experience because this happened to me when I was learning coding, I’ve seen others had this issue where they don’t look up the word and it hurts them, and from my own experience learning Spanish when I even have a rough understanding of a word instead of a complete understanding of the Word, my brain has a really tough time of understanding the sentence that lives in.

Furthermore, it may not be feasible to have tags for all technical words in a step because that may cause the tags to become bloated. We may want to have tags for words like spell forEach but not parameter or HTML, even though these two words are words I have frequently seen people get confused and have cognitive dissonance on. So this particular feature could be a good compliment to the other three, and it wouldn’t be hard to implement or maintain either. I can go into more detail about its implementation in the comments if anybody is curious.

Additional context

Previous issues that have discussed this that I’m aware of: https://github.com/freeCodeCamp/freeCodeCamp/issues/48409 https://github.com/freeCodeCamp/freeCodeCamp/issues/47478

[MyLiege23]

Hi, everyone and @QuincyLarson. I’d like to chime in as a learning developer who’s used freecodecamp and the Odin project, along with some other video tutorials, research, etc. I’m a friend of @oriooctopus, we were talking a little about this last night, and I wanted to input my two cents. I really like the idea of some tooltip reminders for terms. It’s something that would really help me in my learning journey.

So here’s the thing-- I’m a 25 year old male from the US. I’ve used computers all my life, and young folk certainly have intuition about how you’d expect a program/website to operate on your computer. Also, I’ve made it a habit of reading learning material thoroughly, so I haven’t had trouble with terms. Still, I’m at a bias because I’ve already been partially familiar with these terms before I started learning. I’m also in the minority of my peers in that I try to read for 100% comprehension, unlike many of my colleagues from my university who skim readings to get by on tests and pass their classes. In higher education, students are not expected to grasp every term all the time the first time through. Even if they were, people are human, and we forget terms regardless of how well they were conceptualized/defined at their introduction, especially when building new skills. That’s why when you say this:

If we are using terms people don’t understand / remember, then we have failed to phrase the instructions sufficiently clearly.

I understand where you’re coming from in this approach, but I think this issue relates to a different problem than initial comprehensibility. Instead, the problem has everything to do with the delicate process of learning a new skill and the fallibility of memory.

The progression style of freecodecamp does not cultivate comprehensive reading because it’s oriented toward bite-sized chunks and writing little snippets of code at a time, followed by a completion pop-up. This has led many learners to think they don’t need to read all of the instructions and breeze through the course anyway. We tested this on my partner with severe ADHD - She was passing through exercises by chance and not because of comprehension or purposeful code (see the vid here: https://drive.google.com/file/d/1qcqwkn71qj6DFIxyGRTHA7EfI05JY_Gb/view?usp=sharing ). Then when she couldn’t progress through guess & check, she didn’t know how to read the instructions because they included terminology that she didn’t realize she had to memorize as part of the learning process.

Rather than building new features around this, I think we should continue to refine the instructions to where such a feature becomes unnecessary. This is imho not a technology challenge – it’s a communication challenge.

Here’s the thing, changing the course might help, but it’s not going to help in similar scenarios that my peers and I have struggled with. It also sounds like much more work than adding tooltips to coding terms when they’re used in the lessons. This solution is more intuitive for the user and adds minimal bloat to the interface.

We do not want to give learners the wikipedia effect of a paragraph filled with linked text. Instead, we want to avoid terminology where possible, or explain it right there in the paragraph.

I wouldn’t consider the Wikipedia effect a concern here because there’s not a wall of text to begin with. As I said above, the problem has little to do with how a term is taught initially because of human fallibility and normalized learning habits.

I appreciate how much discussion has gone into building a dictionary feature. I think a such a feature would further complicate the already complicated /learn user experience – especially on mobile devices.

There are bigger fish to fry in terms of the site’s functionality, but as I see it, definition tooltips are efficient in learner success compared to the amount of effort it takes to implement. One of the most significant problems of the course is the inability to go back and recover terms/concepts from within a lesson. In order to refresh my memory on concepts and terms, I have to go back to the dashboard of all lessons and select the correct number (the tag system #48800 relieves this problem pretty well).

There is a time and place to learn knew terms and concepts, and it’s probably developerquiz.org (which we will continue to refine) or just continuing to have popular tutorials that rank well on Google. So that if someone googles “what is an element in HTML” they get a well-written freeCodeCamp tutorial.

Also keep in mind we already have DevDocs.io, DeveloperQuiz.org, and have more than 10,000 tutorials on our publication that rank quite well in Google.

This. I recommend adding a mouse-hover tooltip (as @oriooctopus before - we had actually discussed this idea together months ago) that uses the same phrasing and wording as when a term was introduced, in addition to a link to the lesson number where the user learned about the concept. It’s simple, intuitive, and minimally intrusive. Track the usage of the tooltips to support that it’s helping. Whenever I’ve used an interactive text-based learning tool online, I’ve always been relieved to see mouse-hover definitions. It ties things together in an elegant way that doesn’t hinder my flow. A great example of how this was implemented nicely: https://flexboxfroggy.com

Thoughts? Another possible solution is to have “key terms / key concepts” at the top or bottom of the instructions, but this is more bloated.

[RandellDawson]

We had discussed quite a while ago about having a separate tab in the project steps that would auto-populate definitions for key terms we wanted to highlight. @ojeytonwilliams The feature is described in one of the Google Sheets you and I were working on.