New lint rule: Lesson overview items should not be questions.

[nik-rev]

Checks

• [X] This is not a duplicate of an existing issue (please have a look through our open issues list to make sure)
• [X] I have thoroughly read and understand The Odin Project Contributing Guide
• [X] Would you like to work on this issue?

Describe your suggestion

I don't think it makes sense for the bullet points to be questions, they should be instead be statements about what the learner will learn during the lesson

So instead of this:

Lesson overview

This section contains a general overview of topics that you will learn in this lesson.

• How do you declare a variable?
• What are three different ways to declare a variable?
• Which one should you use when?
• What are the rules for naming variables?
• What are operators, operands, and operations?
• What is concatenation and what happens when you add numbers and strings together?
• What are the different types of operators in JavaScript?
• What is the difference between == and ===?
• What are operator precedence values?
• What are the increment/decrement operators?
• What is the difference between prefixing and postfixing them?
• What are assignment operators?
• What is the Unary Plus Operator?

The following may be better:

Lesson overview

This section contains a general overview of topics that you will learn in this lesson.

• How to declare a variable.
• The three different ways to declare a variable.
• Which one to use and when.
• The rules for naming variables.
• Discuss what are operators, operands, and operations.
• Learn about concatenation and what happens when you add numbers and strings together.
• The different types of operators in JavaScript.
• The difference between == and ===.
• Discuss what are operator precedence values.
• What the increment/decrement operators are.
• The difference between prefixing and postfixing them.
• What assignment operators are.
• What the Unary Plus Operator is.

Path

Foundations, Ruby / Rails, Node / JS

Lesson Url

Linter

(Optional) Discord Name

Revenco

(Optional) Additional Comments

No response

[damon314159]

I agree with the idea here, though I think it makes more sense to be a style guide item than to try and enforce it with linting. The most you could do would be to test for a ? character, but that doesn't stop someone writing a question without appropriate punctuation

[mao-sz]

@thatblindgeye Thoughts?

I agree about consistency with lesson overview points not being questions (which also makes more sense for a lesson overview anyway). I'm more inclined to agree with Damon that just having it in the lesson style guide is sufficient, and just rewording any that currently exist as questions to be statements instead, as opposed to making an entire rule for it, which again would only check for ? and not the wording.

[thatblindgeye]

FWIW there was an intent that updating the original section ("Learning outcomes") to "Lesson overview" would include updating the items from questions ("What is XYZ?") to statements ("What XYZ is"). If it's not already part of the style guide it should be added on, which this issue could be converted to doing that if anything.

As a custom rule... I do think that we should probably try to have as many rules that cover what our style guide is conveying as we can. Even if the best way to check whether an LO item is a question is by checking for a "?" at the end, it's not too dissimilar to our rule that checks for inline code in headings. Obviously the difference there is it's pretty difficult to sneak an inline code by, unlike a question being able to omit the question mark ("What is XYZ" or "What is XYZ.").

So I think I'm actually of a differing opinion, in that it may be worth having a custom rule for this. It very much depends on ensuring that it catches more instances than it misses, and that false-positives are kept to a minimum or can easily be fixed by rewording the LO item. For example, maybe something like "What is XYZ and how to implement it" is valid, but could (should?) be reworded as "What XYZ is and how to implement it." Maybe we also enforce that LO items must be worded as a sentence with proper punctuation, i.e. a period.

@MaoShizhong if you wouldn't be totally opposed I'd actually like to see what @nikitarevenco could come up with, keeping in mind that it may end up being something we do decide doesn't work as well as a rule.

[mao-sz]

If Revenco would still like to pursue this, I have no objections then. I've some ideas regarding more than just matching /\?$/ and enforcing ending with a period, but I am interested in what Revenco comes up with if they explore it. I know it was quite a lot of fun exploring how markdownlint and markdown-it handle parsing things and learnt a good amount.

[thatblindgeye]

@nikitarevenco would you still like to be assigned?

[nik-rev]

@nikitarevenco would you still like to be assigned?

Yes, I'm happy to work on this!

[github-actions[bot]]

This issue is stale because it has had no activity for the last 30 days.

[thatblindgeye]

@nikitarevenco just wanted to check in on the status of this issue.

[nik-rev]

@nikitarevenco just wanted to check in on the status of this issue.

I've made the draft PR but I wasn't sure how I can actually test this so I was mostly in the fog when making this. I now realise I should've asked but oh well. I added docs, tests and code for the rule but I don't know how I can test the code without making the PR

And I was expecting the automatic checks to run on the PR but it seems like they aren't

[mao-sz]

Going to reply in the draft PR