freeCodeCamp
freeCodeCamp copied to clipboard
freeCodeCamp
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:
- 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.
- 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:
- 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.
- 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.
- 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
@ahmadabdolsaheb @naomi-lgbt @ojeytonwilliams wanted to follow up on this as I haven't heard anything back. I'm happy to lend a hand in the development.
I wanted to also tag tom but I don't know his github handle
Hi Oliver, thanks for the detailed write-up, it's great to have it somewhere we can all see it.
Last time we discussed this we talked about whether this was intended to be more of a reminder or an aside. Do we see users reading the initial definition, forgetting it and then jogging their memory with this dictionary? Or is it more that we use this as the primary way of introducing technical terms?
I think the consensus was 'reminder', but I wanted to check.
One other thing to consider is are we going to generate these programmatically or require content authors to markup words whose definitions we want to display? Programmatically would involve far less work, but gives us less control over the final outcome. We could end up with some jargon heavy pages looking a little odd. I'm curious what people's thoughts are on this.
Finally, Tom goes by @moT01 here.
I don't think it necessarily needs to function as a "reminder" or an "aside" - it could be both. I think it could be a place where the "official" definition lives - and if someone wants to define the term within the instructions, they can - or if they don't, then campers can use the dictionary if they want. I say this because I don't think it's necessary to define every term the first time it shows up. We want to keep the instructions short, and defining every term in there might get a little busy - also, we would need to go back and rewrite all the steps that failed to define a term. Some of which, is probably needed. Looking at the first few steps, we really failed to define any terms 😬 🤦 The first step has three undefined terms: HTML, element, and tags. Edit: I guess element is kind of defined. That should probably be broken up into two or three steps to introduce those. Step 5 is the first spot I see term, SEO, that probably doesn't need a definition within the instructions - and step 8 has URL. So if it functions as both, it would help campers that want a reminder (and help where we failed to define something) - and it would define terms that we don't need to define in the instructions.
Kind of just thinking out loud - where we have a definition in the instructions, we probably want to try and make it as short as possible. For example, ...add <code> to invoke, or call, the method or HTML is code that defines the structure of a webpage. And the dictionary might have a whole sentence or two with maybe even an example.
Add titles to the steps in the new course format
I was going to say that this might be too tricky since so many of the steps are often very similar - but it would be possible. Is the idea here is that I could look at the titles and find the step that introduces a concept @oriooctopus?
programmatically or manually
I don't know which I like better. Manually seems like too much work to implement and maintain, but it would probably look better. I would probably vote to try and do it programmatically if it's not too hard to see what it looks like.
Last time we discussed this we talked about whether this was intended to be more of a reminder or an aside. Do we see users reading the initial definition, forgetting it and then jogging their memory with this dictionary? Or is it more that we use this as the primary way of introducing technical terms? I think the consensus was 'reminder', but I wanted to check.
Yes you're right I should have clarified on that. My thinking regarding this is twofold:
- The actual functionality or what it would do is still in the air and we can discuss it more in this issue.
- Also regarding the popup: It's probably better to not settle or try to implement anything until we implement the first three solutions I described above or at least settle them in some way. The reason for this is that I view those first three options as not too controversial "core functionality". To me these are things that we almost definitely want and once we implement them we may find that the pop-up feature isn't even necessary because the problem is solved. Or we might find out that the problem is just different and it requires a different solution
I was going to say that this might be too tricky since so many of the steps are often very similar - but it would be possible. Is the idea here is that I could look at the titles and find the step that introduces a concept @oriooctopus?
This weekend I'll try to play around with this a bit and come up with names for the first 10-20 steps out of the responsive design course and new JavaScript course. I'll post them here and we can see how reasonable and useful the naming is
Kind of just thinking out loud - where we have a definition in the instructions, we probably want to try and make it as short as possible. For example, ...add
<code>to invoke, or call, the method or HTML is code that defines the structure of a webpage. And the dictionary might have a whole sentence or two with maybe even an example.
If we get the user acquainted with the idea of a dictionary that they can reference (I'm not talking about the popup, but more something like solution 2 that I described above or even a /dictionary page where you can see the definitions of words with examples) then it would probably be sufficient to just add a link to the dictionary to new words the first time they show up. If in the future they're uncertain of the word that they're seeing, they know that the dictionary feature exists and can just go to it themselves without any handholding
The benefit of having a dictionary that has all these references is that we can go more in depth, plus it means all the content is already written for the popup feature should we decide to add it. The major drawback is that we would have to maintain a bunch of content in a bunch of different languages. In all honesty I think the combination of proposed solution #1 and #2 are just as effective as this without all this extra content to maintain.
@moT01 I went through the beginning of the two new courses creating titles and here are the results. A few notes:
- With the new course format there are definitely some times where there isn't really anything to say in the title. I think this is OK because the title isn't really something intrusive anyways. With that said though, I don't think these really are even titles more like descriptions (I'll refer to them as descriptions from now on). The reason for this distinction is that because all the steps are a part of a larger task rather than just individual lessons on their own it seemed weird for those steps to have a title. Maybe I'm just overthinking things though.
- I mentioned this earlier in this thread but I want to expand on it a bit: These descriptions have the benefit of making it easier for the user to go back to previous content. If a user is on step 93 and they remember that sometime earlier in the chorus they learned about the difference between var and let, they currently don't really have any easy way to identify where they learned it besides clicking through a bunch of different steps.
- I created these descriptions very quickly so obviously they could be improved with a bit more effort
- I followed the title conventions of the old course, and when I could I'd directly copy the title if the lessons were similar enough
Responsive design - the descriptions here worked out really well and I think they'd be quite useful, just as they were in the old course format. 1. Create your first HTML elements 2. Create an H2 Element 3. Create paragraphs with the P element 4. Comment out HTML 5. Add a main tag 6. Nesting elements 7. Add images to your Website 8. Use HTML attributes 9. Add an 'alt' attribute 10. Link to External pages with Anchor elements
Javascript - Things were trickier here since the harder nature of the JavaScript course necessitated more repetition. This makes me a bit less of a fan of adding descriptions, but I still think it's the right choice since there are still a lot of steps where the descriptions are helpful, and I don't think the non-helpful descriptions are obtrusive. 1. 1-14 Boilerplate part "X" 15. Create a script element 16. Logging data to the console with console.log 17. Move your script to its own file 18. Add another console.log 19. Declare a variable 20. Storing values with the assignment operator 21. Practice - Declare variables 22. Variable naming conventions 23. Use the let keyword to declare variables 24. Practice - Declare variables 25. Practice - Declare variables
@moT01 @ahmadabdolsaheb @ojeytonwilliams wanted to follow up on this. Sorry, I know it's basically a wall of text lol
Earlier you said something like (I shortened it)...
regarding the popup: It's probably better to not implement anything until we implement the first three solutions. To me these are things that we almost definitely want and once we implement them we may find that the pop-up feature isn't even necessary
I kind of feel the opposite. The popup is what intrigued me the most, and the implementation you created is really clean. Here's some more thoughts on your first three suggestions...
-
Make sure that we always define a technical word first time it comes up...
We do try to do this, but we don't do it every time - and there may be times where we don't want to include a definition. One issue I have is that we would have to go back and rework a lot of challenges, which may include creating new steps specifically to define a term. I don't have a problem with that - if someone wants to improve the challenges, I'm all for it - It's just a lot of work to get there and, if we do, there's no real way to ensure it stays that way. People may reword something in the future to remove a definition or create a new step without a definition. Maybe I'm being pessimistic - but I feel like we couldn't rely on this to be consistent. Also, some languages have superblocks in different orders - it's just tough.
-
Add tags...
We've discussed this a little (see linked issues above) - and I think we are mostly in favor of something like this. The exact implementation of the tags and how to use them is not clear yet - I gave a suggestion here.
Along these lines, you mentioned a search and/or dictionary page. We had something similar before, you may remember the "guide". It had pages on coding terms, concepts, and technologies - it had some definition style pages, but I think most of the pages were more long-form, almost like our news articles. It was eventually moved to forum posts which were later mostly deleted. I'm not sure we want to try and attempt something like that again. Maybe though. Partially why I am more in favor of the popup or something like that.
-
Add titles...
You came up with some good titles, but you can see how it can be tough to come up with them as well. In general, I like those style titles better, but I'm not sure if we want to do it for these projects. We would maybe end up with a mix of "step 1" type titles and the suggested type. It looks like there might be around 1000 steps in the new RWD - that's a lot of titles to come up with. I'm not really against the titles, just not sure if it's worth it - or if it would even be better for these projects. Also, does it really help solve the issue? Edit: I suppose it kind of does. If you are just looking at the map page, the title might help you find a specific step you are looking for. Double Edit: Actually, the titles aren't even displayed on the map. You just get a number. I don't think we want to move away from that grid display, so I'm not sure if the titles would really help.
So among those suggestions, the tags seem the most valuable to me. I feel like we might be best focusing on that one and maybe just leave the others for now - but feel free to rebut
My argument for the popup. I just like it 😁
I don't think it would be too difficult to implement. We could add a single dictionary.json file with terms as keys and their definitions as values. This would limit what we can put in as a definition, but it would be simple. Not quite sure how to highlight those terms in the markdown - maybe a script to modify the markdown, or perhaps do something at runtime to find them. Then do what you did with the UI. We could then just go through the first 10 steps or something, add the terms we find, and let it grow on its own from there.
The popup partially solves some of the issues you brought up. Users should be able to learn the terms on the fly - I like that the info is just right there. It doesn't solve the problem of being able to find the steps where those terms are taught, though.
My argument for the popup. I just like it. I don't think it would be too difficult to implement.
I like it too but I'm going to disagree with you a little on implementation, if you want to do it accessibly that is :grin: Tooltips are hard to make accessible. Yes, you can use the browser's default tooltip functionality and technically be WCAG compliant, but that doesn't mean it is accessible for everyone (spoiler, it isn't). I did find one pretty good accessible tooltip implementation in Material UI, but even that might have issues for touch screen users. A better option would be to provide a separate button that would trigger a pop-up/modal with the definition. The icon button could be placed directly after the term (a lot of times a lowercase letter "i" is used for the icon). Or perhaps we could add a separate definitions section at the bottom of the instructions that would list each term and the user could click on the term to trigger a modal with the definition. If we did this then we could also use the default tooltip behavior to inline the terms since we would be offering an accessible alternative. I'm sure we can think of other accessible options as well. Just throwing it out there that we should probably not rely on the default tooltip behavior if we want to make these truly accessible.
@moT01
We do try to do this, but we don't do it every time - and there may be times where we don't want to include a definition. One issue I have is that we would have to go back and rework a lot of challenges, which may include creating new steps specifically to define a term. I don't have a problem with that - if someone wants to improve the challenges, I'm all for it - It's just a lot of work to get there and, if we do, there's no real way to ensure it stays that way. People may reword something in the future to remove a definition or create a new step without a definition. Maybe I'm being pessimistic - but I feel like we couldn't rely on this to be consistent. Also, some languages have superblocks in different orders - it's just tough
Yeah this is a good point.
We've discussed this a little (see linked issues above) - and I think we are mostly in favor of something like this. The exact implementation of the tags and how to use them is not clear yet - I gave a suggestion here
Yeah! I saw that and commented on the issue a couple of weeks ago, but it seems like progress is stalled on it/are happening privately. I would love to be involved with this and contribute if you think it's possible for me to do so.
You came up with some good titles, but you can see how it can be tough to come up with them as well. In general, I like those style titles better, but I'm not sure if we want to do it for these projects. We would maybe end up with a mix of "step 1" type titles and the suggested type. It looks like there might be around 1000 steps in the new RWD - that's a lot of titles to come up with. I'm not really against the titles, just not sure if it's worth it - or if it would even be better for these projects. Also, does it really help solve the issue? Edit: I suppose it kind of does. If you are just looking at the map page, the title might help you find a specific step you are looking for. Double Edit: Actually, the titles aren't even displayed on the map. You just get a number. I don't think we want to move away from that grid display, so I'm not sure if the titles would really help.
We agree that there is a problem, and we also agree that it is not straightforward to solve due to design limitations. However, I think that it could be worth solving IF the lack of titles is something that users of the new course have been complaining about frequently. I am not really aware of the feedback users have given about the new core style, maybe part of your scepticism about this comes from the fact that you are familiar with the feedback users have given and this is not a common complaint of theirs. If that is the case then I agree with you 100%; it's not worth solving a problem that users aren't complaining about in the first place. However, if you aren't that involved with the user feedback on the new course would we be able to check with somebody on the team who is to see if this is a common complaint?
My argument for the popup. I just like it 😁
I don't think it would be too difficult to implement. We could add a single dictionary.json file with terms as keys and their definitions as values. This would limit what we can put in as a definition, but it would be simple. Not quite sure how to highlight those terms in the markdown - maybe a script to modify the markdown, or perhaps do something at runtime to find them. Then do what you did with the UI. We could then just go through the first 10 steps or something, add the terms we find, and let it grow on its own from there.
I agree that it would be easy to implement and I would be happy to do it. Perhaps we could just try it out and if users just don't like it we could either tweak it or just remove it. To be cautious, we could keep the underlining fairly stable so that it's not too much of a nuisance and include the ability to "learn" terms so that it's not too annoying. Future additions could include the ability to turn it off all together if some users find it unhelpful.
I like it too but I'm going to disagree with you a little on implementation, if you want to do it accessibly that is 😁 Tooltips are hard to make accessible. Yes, you can use the browser's default tooltip functionality and technically be WCAG compliant, but that doesn't mean it is accessible for everyone (spoiler, it isn't). I did find one pretty good accessible tooltip implementation in Material UI, but even that might have issues for touch screen users. A better option would be to provide a separate button that would trigger a pop-up/modal with the definition. The icon button could be placed directly after the term (a lot of times a lowercase letter "i" is used for the icon). Or perhaps we could add a separate definitions section at the bottom of the instructions that would list each term and the user could click on the term to trigger a modal with the definition. If we did this then we could also use the default tooltip behavior to inline the terms since we would be offering an accessible alternative. I'm sure we can think of other accessible options as well. Just throwing it out there that we should probably not rely on the default tooltip behavior if we want to make these truly accessible.
@bbsmooth I could see challenges here with accessibility. At my company we do make tooltips decently accessible by making them tab indexable so that screen readers and keyboard-only users can access them. However, overall I think it's OK if it's not totally compliant since this is more of an "extra" feature and not a core feature. If the feature is successful later on we could also improve the accessibility further with the points you've brought up.
My final thought on this is that before moving forward on the popup feature I think it's important to first get a rough idea of the tagging/dictionary feature. @moT01 you mentioned previously there could potentially be a set of definitions associated with these tags. Perhaps we want to share this text between the dictionary feature and the tag feature to improve scalability. Because of that prospect, I think it would be good to at least have a very rough idea of what we want to do with the tagging/Dictionary feature before I get started on this pop-up feature
For what it's worth, the only complaints I have seen about lack of titles is that it's hard to search for where concepts are taught - which would be fixed independently. I don't believe we need to give the steps titles.
I could see challenges here with accessibility. At my company we do make tooltips decently accessible by making them tab indexable so that screen readers and keyboard-only users can access them. However, overall I think it's OK if it's not totally compliant since this is more of an "extra" feature and not a core feature. If the feature is successful later on we could also improve the accessibility further with the points you've brought up.
My concern here would be that if we implement a tooltip, we'll inevitably come to rely on it for conveying definitions - it'll impact how we write the actual instructions. And this will turn it into a core feature.
I think it's OK if it's not totally compliant since this is more of an "extra" feature and not a core feature.
I'm not sure I would make that distinction. If a feature is good for some users then all users should be able to take advantage of it. Especially when we have perfectly acceptable alternatives, such as toggle tips.
Or perhaps we could add a separate definitions section at the bottom of the instructions that would list each term and the user could click on the term to trigger a modal with the definition
This approach sounds really promising. One concern I had with the tooltips is that they could be way more intrusive for someone listening than someone reading. For example if it's, essentially
Reading:
A sentence with a definition in it
vs
Listening:
A sentence with a definition tooltip here in it
that would break you out of the flow.
My concern here would be that if we implement a tooltip, we'll inevitably come to rely on it for conveying definitions - it'll impact how we write the actual instructions. And this will turn it into a core feature.
Good point
Or perhaps we could add a separate definitions section at the bottom of the instructions that would list each term and the user could click on the term to trigger a modal with the definition
Would this only include the terms that are introduced in that step? Or would it also include any technical term that are mentioned? A third option is to include the new terms and perhaps if there are any other crucial terms that were previously mentioned those are also included.
Or perhaps we could add a separate definitions section at the bottom of the instructions that would list each term and the user could click on the term to trigger a modal with the definition
I don't like this. I would prefer to keep the instructions and the items around it as minimal as possible. I would rather put them in the notes or the tooltip or something
My concern here would be that if we implement a tooltip, we'll inevitably come to rely on it for conveying definitions - it'll impact how we write the actual instructions.
That's a possibility, we probably don't want that to happen - that may not necessarily be a bad thing, though. It might allow us to shorten the instructions. But yea, we can't stop defining things in the instructions - that's what they're supposed to do. The benefit is that users can quickly review the terms in the instructions, which I think is pretty nice.
I think we need to try and clarify some things before we continue to make sure we are on the same page - it sounds like we are kind of talking about two things:
-
The tags: These would tag challenges (probably in the markdown frontmatter?) so we know what they cover. e.g.
splice,margin, ordiv. So we could then use these tags to find challenges that cover certain topics. I feel like we probably don't want to tag every challenge that uses a div with thedivtag, there would probably be 100 challenges with it. Or maybe we do - not sure. This really wouldn't be functional without a search feature, or maybe just displaying the tags somewhere? I'm not sure if we want to include challenges in the existing search bar - pretty sure we used to do that, but stopped. I think we want that only for news articles, but I'm not sure. So I'm not really seeing how we would put these to use, but I definitely see a benefit. -
The dictionary: would then define these tags somewhere? Or would these be different than the tags? I think these would be different than the tags because we don't necessarily want to tag a challenge with
boilerplateorinvokejust because it's mentioned in the instructions (or maybe we do), but we want campers to be able to quickly see those definitions. I also kind of feel like we need to do this programmatically - maintaining it otherwise probably wouldn't be great.
The first challenge, for instance, would probably want to be tagged with only h1 - we wouldn't want to tag it with h1, HTML, element, and tags. The latter three would be in the dictionary.
The second challenge would maybe be tagged with h1, h2, h3, h4, h5, h6, and then use the dictionary for heading and elements.
So things like element and div appear all over the place in the curriculum, do we want to tag all the challenges with those or just have the definition available? Tagging all of them kind of feels like it defeats the purpose.
^ Just trying to figure out what it might look like in practice. I'm not sure if this is what we were thinking or what.
I'd argue that we would only want to tag challenges with the specific concepts that are being taught in that challenge.
That is, the challenge that teaches a div gets tagged with div, and the challenges that use divs but aren't teaching it don't get tags.
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.
@moT01 I agree with your distinction between tagging and definitions.
I'd argue that we would only want to tag challenges with the specific concepts that are being taught in that challenge.
That is, the challenge that teaches a div gets tagged with div, and the challenges that use divs but aren't teaching it don't get tags.
Also agreed
So it seems like there is pretty broad consensus on the need for tagging, there is also consensus (although I remember it not being universal, this thread is getting long haha) on the need for some sort of mechanism to make it easy for users to find definitions. However, we disagree on what that mechanism would be. I'm now going to summarize the three proposed mechanisms just to get everybody on the same page.
- One thing to note is that for the sake of focus the below text in this comment is just related to the mechanism for finding definitions within a lesson. What's not discussed below is the specifics of tagging or the standalone dictionary page(s) that exists outside of lessons.
- A separate page - @RandellDawson suggested this in the comment above this one. This has the benefits of allowing us to define a lot of terms without crowding out the initial lesson, however one drawback that may be significant is that users might not use it as much because it's not as 'right there' as the other two mechanisms
- There's the popup method that I suggested - This involves faintly underlining terms and then on hover showining a popup with the definition. At the initial comment on this issue even see a video of it. Concerns for this include accessibility (which I think is solveable) and figuring out which terms should have a pop up or not (we don't want "div" to be underlined in the 100th challenge)
- Another option is to show separate definitions section at the bottom of the instructions that would list each term and the user could click on the term to trigger a modal with the definition - To me a modal seems like overkill, we could also potentially have it just be a popover or be like an accordian/expansion below. One drawback brought up by @moT01 is "I would prefer to keep the instructions and the items around it as minimal as possible". However, I don't really see how this bloats the instructions, as it's all optional. For clarity, I've created a demo of what I imagine this feature to be like. After seeing it, I actually really like it. Considering that the popup method I proposed has been controversial, this is currently what I see is the best way forward.
https://user-images.githubusercontent.com/20331238/206345477-b4de4b78-dd92-4060-9c13-6b2ee9e746cf.mp4
I think there are other mechanisms not mentioned above that we haven't thought about yet as well, so if anybody else has other ideas besides the three mentioned above that would be great. I see this feature as a small, but core part of the user experience so getting it right means a lot of positive effects.
As Tooltip and tooltip like patterns are widely used for definitions, I recommend we stick to this convention and come up with an accessible implementation.
If our implementation does not check all the boxes, we could implement the Notes tab in addition to the tooltips. As Tom and Randy mentioned, the initial spec of the multifile editor included an additional tab with a few sections (Definitions, Tests, solution, etc.) to give users more context for each challenge.
Finally, I think adding tags are a great idea. We could structure our challenges and could come up with loads of features to shorten the user journey: build definition lists ( randy sheets ), tag pages, link challenges with same tags, etc.
I think that if there was also tests tab and solutions tab then it would normalize the user switching tabs as part of their normal workflow. In that case having a definitions tab makes more sense to me. Something I'm also thinking about is perhaps we could do a combination of that and a tooltip solution. Whichever words are underlined in the main text also would show up in the definitions tab. Regarding which words are underlined, I think that we would probably just stick with which ever tags belong to that lesson. However if we had a definitions tab we could also have a search box where they could search for any definitions.
@RandellDawson it took me a while to track this down, but we did indeed:
When certain keywords appear in the step description/instructions, a special icon will appear beside it inline that allows users to click and/or mouseover to see a definition in a popup (window) or modal for mobile. The definitions will be stored and controlled in a json file that will serve as a lookup. This allows us to use the same definitions across all challenges when those keywords are used. These definitions would be markdown format.
what we've been discussing here is a little more refined, but it's nice to see we're all thinking along the same lines.
If we implement a separate tab in which we can display the terms and definitions then I think we could get away with using the built in browser tooltip functionality since there would be a reasonably equivalent method for people who can't take advantage of tooltips to still get the same information. Otherwise, I would strongly urge that we use a toggle tip instead of a tooltip. Tooltips can be annoying for screen reader users because the content in the tooltip will be automatically read to them whether they want it or not. At least with a toggle tip they will have the option of whether they want to hear that content.
I like where this is going, I think having this dual approach of underlining/tooltiping words in the main tab and also having a separate definitions tab is a solid way forward.
One behavior that I think still needs to be settled on is which words are highlighted in the main tab.
Recent comments have focused on only highlighting the words that are tagged in a lesson's metadata. That means only highlighting a very small number of terms per lesson, somewhere between 0 and 3 in most cases.
The issue with this is outside of these new terms, there is still a need for functionality that would help students to understand or refresh their understanding of certain words that are not tagged/new. For example:
- Words that either may not have been defined previously that we overlooked (such as "boilerplate").
- Words that the student once knew but forgot. This could potentially be any word, it usually takes multiple mentions of a word for somebody to commit it to memory. Furthermore, many students often take long breaks of weeks or months before coming back to Free Code Camp and forget a lot by the time they come back. These are the reasons why I initially proposed having the tooltip for all words that existed in our dictionary and were in the lesson.
The two main concerns with this approach that were raised when it was first proposed were that it could end up highlighting too many words and it could be an accessibility issue. With this dual approach the accessibility question has mostly been solved. Regarding the issue of highlighting too many words I think that this can be solved by combining two different solutions:
- As mentioned above in the bottom right corner of the tooltip there would be an "I know this word button" or maybe even more simply just a checkmark. If a user clicks on that button the word will no longer show the underline/tooltip.
- The user could toggle their highlight mode which could either be "None", "Tagged/new words only", "All unlearned words". The "All unlearned words" mode would be whichever words are in the dictionary where the user has not yet clicked on the "I know this word button".
If we are worried about logged out users not being able to benefit from solution one then we can have logged out users default to "Tagged/new words only". Also, I want to mention that I am concerned that if we do it this way perhaps users won't know about the ability to toggle between the different modes and therefore won't use it. However, I think this would only be an issue if we didn't put enough attention towards that when making the design. I can elaborate further if anybody would like me too as I have some ideas on how to avoid this issue.
Regarding how this spills over to the definitions tab, I think there are a couple of solutions:
- There could be two sections in that tab; the first is the "tagged" or "new" words section, and then an "All words" section.
- In the definitions tab we could also have a search bar where the user can search for any term in the dictionary to find a definition. A benefit of this is it means that if a user clicks on the "I know this word button" they can still easily find the word by searching for it here.
I think it is important that our implementation of this feature does not discourage campers from learning how to search for things they have forgotten.
While I agree that user's knowing how to google is the ideal generally, I think it only works if we can really get users in the habit of doing it.
I think the Odin project does a really good job of encouraging users to Google because from the get-go it forces you to have to Google lots of things and setup a dev environment on your computer, all with minimal instructions from the site itself. I have always thought of free code camp as on the other side of the spectrum. It is much more self-contained and therefore more accessible, not to mention that it avoid scaring people away which is something that I've seen happen when people try to get started with The Odin Project. In my opinion these are structural choices and each have their pros and cons. From what I've observed, Free Code Camp's model seems to come at the expense of certain types of self-sufficiency, at least in comparison.
To further elaborate on this in this particular case, the site is designed to be an encapsulated source of information to start from zero and reach junior level. Even when there is further branching out, it's later on in the course when the user is more experienced. My concern with using googling to search for definitions is that since understanding terminology is an important part of the learning experience, googling now takes a core role in the learning experience.
That seems problematic to me because even though it seems simple a lot of people don't know how to Google with any level of proficiency. That may be a controversial opinion but it's what I found from teaching people who didn't have a ton of access to technology in their life, especially people who grew up poor, grew up in an underdeveloped countries, or are older. Things get even trickier in less popular languages where there may be very few coding resources or simply just low quality resources. MDN is only in 6 languages for example. This is one reason why the Odin project model would have a hard time scaling beyond English, and why the Free Code Camp model can scale really well to any language.
When I was creating my own website to teach programming I opted for a hybrid approach and created a few different lessons and exercises to teach the skill of googling. I haven't seen something like that in Free Code Camp, besides maybe a forum post that I remember from a long time ago. If we did want to try and make googling be a core part of the experience I would say that some sort of structured way of teaching the skill would be essential.
So to summarize, in our case I don't think it's ideal to rely on googling in the intro courses (I think it's ok in the more advanced courses like React and JS libraries) because I think it opens up a can of worms and is a bit incongruent with the way Free Code Camp operates.
There's a lot of discussion here, I may have missed some points - but I dunno about all of it. It feels like we might be over-complicating it…
standalone dictionary page(s)
I would lean against the stand-alone dictionary page(s) for now. I just don't see the benefit at the moment. Like I said, we used to have the "guide", but ended up removing it. I wouldn't rule it out, but I think that’s something we can look into later on. In my opinion, the main purpose of the dictionary is so campers can quickly see definitions of things they don’t recall or weren't defined while they are on a step. I would make that the MVP functionality.
separate tab to display terms and definitions and the built in browser tooltip
Maybe I'm not understanding it fully, but I don't think I'm in favor of this dual approach. I would stick with one or the other. In my opinion, putting the same information on a page twice is unnecessarily redundant and provides more ways for campers to get distracted. I think we want this to be unobtrusive and make sure to keep the lesson the main focus.
Ahmad mentioned that "tooltip like patterns are widely used for definitions, I recommend we stick to this convention." I think we should go with that, as well. Reminder: A "notes" tab does already exist in case we want to go that route - no pages are using it at the moment.
search box where they could search for any definitions
I would not allow campers to search for definitions within a step. The project based curriculum is meant to get campers into a "flow state" - this seems potentially distracting to me. In my opinion, a step should only include the exact information a camper needs to complete it. I wouldn't rule it out, but I wouldn't include it as part of the MVP.
Regarding the "flow state" - I think the RDB section does this really well (I'm a little biased) - I recommend giving it a try if you haven't. Quincy and I had a lot of back and fourth on how the steps should be and I think I was able to bring his vision to life. All of this extra stuff takes away from campers being able to get into a rhythm - so I really think we should try to keep as minimal as possible to start.
The above is just my opinion. I'm not trying to shoot down these ideas - they are all worth discussing - but it seems like a lot of different features. I think we should try to find the easiest and most unobtrusive way to implement a dictionary feature, focus on that, and we can discuss adding additional features from there. Or, potentially, find the easiest way to do the tags - but I think that will be a little more involved, we would have to tag every lesson.
There's a lot of discussion here, I may have missed some points - but I dunno about all of it. It feels like we might be over-complicating it…
I think it might be a good idea to have a meeting where we can discuss and settle this, like we did when we first began discussing the issue. I think this is a really complicated feature, not in terms of implementation but just simply finding the best solution is hard because there are so many different perspectives and potential ways of doing it.
I would not allow campers to search for definitions within a step. The project based curriculum is meant to get campers into a "flow state" - this seems potentially distracting to me. In my opinion, a step should only include the exact information a camper needs to complete it. I wouldn't rule it out, but I wouldn't include it as part of the MVP.
Yeah this is a good point, I agree. Flow state is super important and putting information in this other tab would probably do more harm than good. The tab was initially proposed though as a solution to the accessibility issue, so we have to make sure that if we don't include a tab we arrive at a solution that is acceptable from an accessibility perspective.
Or, potentially, find the easiest way to do the tags - but I think that will be a little more involved, we would have to tag every lesson.
To me the benefit of tags is not just for the Dictionary feature but also for the search feature. However I could also see us using our Algolia and instead of searching for tags indexing all lesson text. Algolia is a pretty easy and cheap way to do this (it may even be free), I've done it before on a couple of sites.