Controllers: code instructions are non-committal at times.

[RyanMcEntire]

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
• [ ] Would you like to work on this issue?

Describe your suggestion

Throughout the Express learning module, it is difficult to tell the difference between code that is used as an example to show a concept, and code that you are supposed to add to your own app. The descriptions are not always decisive and clear. The lessons contain a high amount of passive voice

An example is the "creating custom errors" section.

Also, by the end of the lesson, it says we are supposed to have routes/userRoutes.js if we were following along.

Maybe i'm blind, but if the instructions are there, it doesn't seem like they were explicit. I went back to review previous lessons and couldn't find anything concrete.

The recap also shows us using the CustomNotFoundError() without showing where it was defined in the project. It doesn't appear in the recap for the page, and also doesn't appear in the diagram showing you what file structure you should be mimmicking at that time.

The original introduction of this custom error also doesn't explain where the author is putting it or where the reader should be putting it.

In the Views lesson as well, the reusable templates section carries a passive voice throughout all the code examples: "You may want to include..." "Say you have the following navbar component..." "You can insert this component into..." "This can be used to" "you can pass it when rendering index.ejs which contains the navbar..."

Then in the middle of a paragraph, suddenly switches to an imperative command "Modify app.js such that a links object is defined and passed..."

At this point i get confused and have to retrace my steps and figure out if I was supposed to be adding everything before or not. There's no clear indication for the reader that gives me confidence that "This is an example.", "Add this code to your project."

I would prefer if the instructions were more explicit.

Path

Node / JS

Lesson Url

https://www.theodinproject.com/lessons/nodejs-controllers https://www.theodinproject.com/lessons/nodejs-views#reusable-templates

(Optional) Discord Name

clowdy

(Optional) Additional Comments

No response

[MaoShizhong]

Many thanks @RyanMcEntire. This is exactly the sort of feedback we want and need after the release! While writing and reviewing, we try our best to consider things from the perspective of a learner going through for the first time, naturally, there will be some bias from preexisting knowledge/intent etc. So this kind of detailed and practical feedback with examples is super helpful.

@fcasibu mind taking a look at this when you get the time? I think you'll be best poised for initial thoughts here since you'll know your intentions best from when you wrote the lesson, and what parts may be amended and how. For reference, the Views lesson is receiving some updates along this vein in #28535, if that helps.

[fcasibu]

Hi @MaoShizhong sure, now seeing the routes lesson in place, I have an idea on how to change it, I'll consider making it flow with the previous lesson.

Also for the CustomNotFoundError I considered it just as an "option" but I guess since I stated:

We can then use this custom error class and refactor the earlier version of getUserById like so:

It seems like the new replacement and should be added in code.

Also thanks for creating an issue @RyanMcEntire appreciate it. Any other sections you think is in passive voice?

[github-actions[bot]]

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