Feedback - Improper demonstration of functions file in demonstration on Beginner WordPress Developer / Action Hooks

[mikeritter]

Type of feedback

//content

Description

The Action Hook example in the module demonstrates adding the hook to TwentyTwentyfour theme functions.php file which is bad practice. While extending a parent theme is outside the scope of this introductory module and the example is quickly demonstrable, this example is presented without any warning how directly editing a theme's files instead of extending it will break. Much better to demonstrate the proper method through a plugin as was already demonstrated in the course.

View at https://learn.wordpress.org/lesson/action-hooks/

Step-by-step reproduction instructions (optional)

Screenshots or screen recording (optional)

Other information (optional)

[mikeritter]

Note: this is repeated in the following filters lesson

[jonathanbossenger]

Thanks for the feedback @mikeritter.

Would you agree the following note at the top of the lesson would be a sufficient warning:

Please note that the code examples in this lesson are for demonstrative purposes only. We do not recommend directly editing a theme's functions.php file if you want to make changes to the theme for any reason.

[mikeritter]

The disclaimer should go in a prominent place in the website content where the code appears with alert/callout styling. Ideally there would also be a pop-up in the YouTube video -- which I believe can be edited to add a pop-up -- that explains the example is for demonstration purposes only with a link in both places to explanation.

Ideally, when this lesson is revisited and revised it should be demonstrated in a plug-in file. Also, there should be a note for everyone developing training content to avoid this pitfall and to reinforce best practices in demonstrations.

Thank you for all of the hard work on this series. I have been developing with WordPress for years and it encapsulates some essential functions really well! It is a truly valuable contribution to the community! The demonstration of custom post types, custom tables, and taxonomies is worth the time invested.

[jonathanbossenger]

The disclaimer should go in a prominent place in the website content where the code appears with alert/callout styling. Ideally there would also be a pop-up in the YouTube video -- which I believe can be edited to add a pop-up -- that explains the example is for demonstration purposes only with a link in both places to explanation.

Yes, I intend to edit the disclaimer into the actual video content, before the code examples, so that it is organically part of the actual lesson. Then I plan to highlight the disclaimer in the lesson text in a callout.

Ideally, when this lesson is revisited and revised it should be demonstrated in a plug-in file. Also, there should be a note for everyone developing training content to avoid this pitfall and to reinforce best practices in demonstrations.

Believe me, I had a long argument with myself about this very same problem. We strive to follow best practices at all times. However, we're also trying to balance the ability of the new learner to quickly learn the new concept with little prerequisite knowledge.

In this case, if the learner is working through the beginner developer learning pathway, they have not even learned what a WordPress plugin is yet or how to create one correctly. However, if they have completed the previous lessons, they do have an active WordPress install with an active theme that they can hack.

I did consider moving the module on hooks to after the modules on plugin and theme development, but that also didn't make sense, as those modules require the knowledge that the hooks lessons cover.

Sometimes, teaching new concepts to learners might require an example or demonstration that is not generally considered a good idea in the real world. If that example or demonstration allows the learner to fully grasp the new concept, and we explain why the example is not a real-world one, then we keep them engaged enough to continue learning, which is where we can introduce the best practices. However, if it's too hard for them to be successful at the very first tasks, then we risk losing them entirely.

[mikeritter]

I seem to recall using a simple plugin file earlier in this series already, so it would not be new in this context.

The disclaimer should go in a prominent place in the website content where the code appears with alert/callout styling. Ideally there would also be a pop-up in the YouTube video -- which I believe can be edited to add a pop-up -- that explains the example is for demonstration purposes only with a link in both places to explanation.

Yes, I intend to edit the disclaimer into the actual video content, before the code examples, so that it is organically part of the actual lesson. Then I plan to highlight the disclaimer in the lesson text in a callout.

Ideally, when this lesson is revisited and revised it should be demonstrated in a plug-in file. Also, there should be a note for everyone developing training content to avoid this pitfall and to reinforce best practices in demonstrations.

Believe me, I had a long argument with myself about this very same problem. We strive to follow best practices at all times. However, we're also trying to balance the ability of the new learner to quickly learn the new concept with little prerequisite knowledge.

In this case, if the learner is working through the beginner developer learning pathway, they have not even learned what a WordPress plugin is yet or how to create one correctly. However, if they have completed the previous lessons, they do have an active WordPress install with an active theme that they can hack.

I did consider moving the module on hooks to after the modules on plugin and theme development, but that also didn't make sense, as those modules require the knowledge that the hooks lessons cover.

Sometimes, teaching new concepts to learners might require an example or demonstration that is not generally considered a good idea in the real world. If that example or demonstration allows the learner to fully grasp the new concept, and we explain why the example is not a real-world one, then we keep them engaged enough to continue learning, which is where we can introduce the best practices. However, if it's too hard for them to be successful at the very first tasks, then we risk losing them entirely.

[jonathanbossenger]

The two lessons have been updated with the appropriate notice in both the video and the text.