Introduction to WordPress Coding Standards

[jonathanbossenger]

Details

• Content type (Online Workshop, Lesson, Course, Tutorial, or Lesson Plan): Lesson
• Content title: Introduction to WordPress Coding Standards
• Topic description: Explain to the new developer to the concept of coding standards and why they are important. Then, the WordPress coding standards for each programming language, CSS, HTML, JavaScript, and PHP, will be introduced.
  PHP Coding Standards
• Audience (User, Developer, Designer, Contributor, etc.): Developer
• Experience Level (Beginner, Intermediate, Advanced, Any): Beginner

Prerequisites

It is assumed that the learner has already completed the following lessons:

• Beginner WordPress developer
  • Modules 1 - 3

This new lesson will form part of module 3

Learning Objectives

• Describe what coding standards are and why they are important
• Identify the four different WordPress Coding Standards for each programming language in the WordPress stack

Related Resources and Other Notes

• https://developer.wordpress.org/coding-standards/wordpress-coding-standards/
• https://www.youtube.com/watch?v=ccKcQHzHF8o

Automation Code

//lesson:

[github-actions]

Lesson Development Checklist

• Gather any relevant links to Support, Docs, or related material
• Description and Objectives finalized
• Lesson created and announced to the team for review
• Lesson reviewed
• Lesson video submitted and published to WPTV
• Lesson created on Learn.WordPress.org
• Lesson video published to YouTube
• Lesson on Learn.WordPress.org updated with YouTube video
• Lesson published to Learn.WordPress.org

[jonathanbossenger]

Script for review: https://github.com/jonathanbossenger/wp-content/blob/main/developer-learning-pathway/03-the-programming-languages-of-wordpress/06-coding-standards.md

[eirichmond]

Thanks, @jonathanbossenger! This is a great start. At first glance, I've spotted a typo. Can I edit if I'm assigned, or would you prefer I just add the corrections in the comments?

[jonathanbossenger]

Should I fork the project and submit a PR, or would you prefer I just add the corrections in the comments?

Sorry, just realised its not a repo to folk ><

It is actually 😁 https://github.com/jonathanbossenger/wp-content

Would it be easier if I just added you as a collaborator on that repository, then you can edit any typos as you see fit.

[jonathanbossenger]

@eirichmond, when you have a moment, it would also be helpful if you could add an ETA for the first version of the video.

As you are a volunteer contributor, please make sure you give yourself enough time.

[eirichmond]

@jonathanbossenger from a script POV there's not a lot to do, you've done all the hard work on this already, it will only be the time it take to record the audio with some post production, then figure out the A/B rolls with any graphics, so... I'd estimate a first rough cut by the end of next week/early the following week.

[eirichmond]

@jonathanbossenger I've just commited some final adjustments, if you happy with them, I'll proceed with getting the audio done in the coming days.

[jonathanbossenger]

@eirichmond no complaints from me, feel free to proceed.

I'd estimate a first rough cut by the end of next week/early the following week.

Thank you, that's perfect. I mostly ask so that we have an agreed upon date to work towards.

[eirichmond]

Hey @jonathanbossenger, here is my first draft, I don't want to go to much further until I know I'm not breaking any guidelines, feedback welcome.

draft-coding-standards.mov

[eirichmond]

The audio seems to have been stripped out for me in the last comment so, here is another link to the Video

[eirichmond]

@jonathanbossenger Oddly enough, the first comment does have audio if you view it on the mobile app, but not in a browser—at least for me! Let me know your thoughts once you've had a chance to review the progress so far. If everything looks good, I'll go ahead and continue with the rest of the sections.

[jonathanbossenger]

Hi @eirichmond I'm not sure why that is, but I can definitely hear sound on both options. I tried to check on Firefox, and it looks like you can't enable sound for embedded videos if you're not logged into Github, but that's all I could find.

Ok, on to feedback on your video sample:

• Your speaking voice is great, evenly paced, and clear. One small piece of advice I can share here is to try and use facial expressions to emote when doing voice recording. For example, weird as it may sound, if you smile while recording your voice, it actually makes the voice sound friendlier. I don't always get this right, but I find it helps to imagine I'm actually presenting to a group of people when I record.
• Overall the visuals are great, if a little fast/overwhelming. If I had one piece of constructive feedback regarding the visuals, it would be to either use fewer visuals and/or visual transitions or less in the way of animations/slower animations. A good example of this is the use of visuals/animations a different video editor created on the lessons about debugging in the beginner developer learning pathway (example lesson - https://learn.wordpress.org/lesson/the-built-in-wordpress-debugging-options/).

Otherwise, it's a great start, and I look forward to seeing your final video.

[eirichmond]

@jonathanbossenger Perfect feedback, thank you. I think I might redo the audio; I know exactly what you mean. This is really useful feedback for me in general, so thank you. I fully understand what you mean about the speed of the graphics too. I think the pace of the narrative defines the speed of the graphics. To be honest, I did struggle a little to get the graphics in because of the pace of the audio, so fixing one will inevitably fix the other. Thanks again, I appreciate it.

[eirichmond]

@jonathanbossenger here is the completed video, I've re dubbed the audio and taken onboard your comments re the animation to slow things down a little, let me know your thoughts complete video here

[jonathanbossenger]

Thanks @eirichmond. Could you make the video public please.

[eirichmond]

@jonathanbossenger yes, I've just granted you access.

[jonathanbossenger]

Thanks, @eirichmond. I took a quick look yesterday, and I do have a few suggestions, but I also don't see why we can't open this up for a public review from other members of the training team. If you're ok to move this into the next step in the process, please make the video available publicly, and I'll update the status.

[eirichmond]

Thanks @jonathanbossenger - video is now public.

[jonathanbossenger]

Perfect, thank you.

[jonathanbossenger]

This lesson video is now ready for review:

• Lesson script: https://github.com/jonathanbossenger/wp-content/blob/main/developer-learning-pathway/03-the-programming-languages-of-wordpress/06-coding-standards.md
• Lesson video: https://drive.google.com/file/d/1kgNHbKsg3zsgVDwTGFnwUHLrJ2tV_EVO/view?usp=sharing

Please review this video by following the guidelines for reviewing content.

[digitalchild]

When you go into detail for the standards, I think it would be good to have a screenshot or two of code to demonstrate what those standards mean, like you did with the HTML at the beginning.

The video animations are great.

Tutorial/Lessons Review Checklist

Please tick all items you've confirmed:

• Learning outcomes/objectives are clear.
• Technical concepts introduced in the content are accurate.
• The speed of demonstrations are easy to follow.
• The narration audio matches what is shown visually.
• Spelling and grammar are correct.
• Sound quality is consistent throughout the video.
• Brand Usage Guidelines and Promotional Guidelines are being followed.
• Media assets are all in the public domain (CC0).

[eirichmond]

Thanks @digitalchild, thats a great idea, I'll revisit this and update the video. Anything else to add before I do that @jonathanbossenger ?

[jonathanbossenger]

Tutorial/Lessons Review Checklist

• Learning outcomes/objectives are clear.
• Technical concepts introduced in the content are accurate.
• The speed of demonstrations are easy to follow.
• The narration audio matches what is shown visually.
• Spelling and grammar are correct.
• Sound quality is consistent throughout the video.
• Brand Usage Guidelines and Promotional Guidelines are being followed.
• Media assets are all in the public domain (CC0).

@eirichmond thank you for an excellent video, I also like the way you use animations, especially the scrolling list of section heading/sub headings for each .

I also really like how you showed/animated the actual pages from the documentation on wp-scripts, and the readme for PHPCS. It's helpful when folks see these real world web pages, so that when they go looking for them online, they can see it's the same thing.

A couple of suggestions:

I didn't mark "The narration audio matches what is shown visually" above because in the video whereever you have a section title (example at 0:20) there's no spoken voice. We've had feedback in the past that this is not an ideal, and we should try to always describe whatever is shown visually on screen.

I agree with @digitalchild's feedback, it would be great if you could implement a sample code example from the specific coding standard you're covering in that section. Even a screenshot of one of the examples from the individual handbooks would be great.

Additionally, it would be nice if we could add either a screenshot of the coding standards handbook and the separate coding standard pages when they are introduced:

• 1:35 - screenshot of handbook
• 2:00 - screenshot of HTML standards page
• 2:30 - screenshot of CSS standards page
• 2:55 - screenshot of JS standards page
• 3:15 - screenshot of JS standards page

(This doesn't have to be at these exact times; I'm just including the times when these sections are started)

This also gives the learner a visual link from the video to the actual page in the handbook.

I usually include a full-screen view of the web page in question, but other video editors like Agil include the screenshot alongside some text (example lesson), and I could see that working as well. One suggestion on including this would be to have the screenshot of the specific page in the docs at the same time as the section title.

It's up to you to decide which way to go, but I think including it helps the learner make the visual connection from the video to the actual pages in the docs.

[eirichmond]

@jonathanbossenger Thank you! This is all very helpful feedback. I'll revisit the draft and implement all the new suggestions.

[eirichmond]

@jonathanbossenger @digitalchild I've made amendments to the first draft ready for review, looking forward to your feedback Draft 2

[jonathanbossenger]

@eirichmond This is quite excellent. It's nicely done! I'm going to have to start implementing some animations into my videos to up my game 😁

Personally, I am very happy to consider this ready to publish.

Would you like to work through the process of getting it published and added to the relevant place in Learn WordPress, or would you prefer me to handle that, and we can start looking for other scripts for you to create videos for?

[eirichmond]

@jonathanbossenger That's awesome! Thanks for the kind words. I'm happy to walk you through the publishing process if you'd like. It would be beneficial for future contributions? Happy to start on the next project as well 👍

[jonathanbossenger]

@eirichmond excellent.

I'm happy to walk you through the publishing process if you'd like. It would be beneficial for future contributions?

So typically, the process here is:

1. Create a video thumbnail for the video
2. Generate subtitles for the video
3. Upload the video to WordPress.tv
4. Create the lesson on Learn.WordPress.org
5. Once the video is synced to the WordPress YouTube account, add the video description and chapter markers to the video in the YouTube account
6. Publish the final lesson on Learn.WordPress.org.

Currently, you can do steps 1, 2, and 3. Step 4 requires you to ask for access (details in the linked doc) step 5 is only available to folks with access to manage videos on YouTube (in this case me), Step 7 you'll be able to do yourself, once you have the access from Step 4.

However, because this lesson is part of an existing module, I'd like to create the thumbnail, as I have a Icon set (Font Awesome) I've been using for those modules, that I'd like to reuse for the thumbnail for this lesson (for continuity).

So how does this work for you?

1. I'll create the thumbnail so that it matches the current lesson in those modules, and upload it here
2. You can (if you like) generate the subtitles. Note that I have an automated script I use, so I'm happy to do this for you
3. You upload the video to WordPress.tv
4. You send me your chapter markers in a comment on this issue
5. I'll handle publishing it on YouTube
6. You can handle creating on Learn.WordPress.org, I'll just do a final review before we publish.

[jonathanbossenger]

Happy to start on the next project as well 👍

Excellent. The next lesson I plan to work on is #2718 so how about we collab on that one next? If you're keen, please comment on that issue, so I can assign you.

[jonathanbossenger]

WordPress TV Video: https://wordpress.tv/2024/10/10/introduction-to-wordpress-coding-standards/

[jonathanbossenger]

YouTube URL: https://youtu.be/n7-F-FMzM7Q

[jonathanbossenger]

@eirichmond, I hope you don't mind; I went ahead and added the videos to WordPress.tv and YouTube. I'll add you to Learn.WordPress.org in a bit so you can create the lesson there.

[eirichmond]

@eirichmond, I hope you don't mind; I went ahead and added the videos to WordPress.tv and YouTube. I'll add you to Learn.WordPress.org in a bit so you can create the lesson there.

Not an issue at all, it's nice to see it out there in the wild as it were 👍

[jonathanbossenger]

Lesson thumbnail:

[jonathanbossenger]

@eirichmond I've sent you an invite to Learn.WordPress.org with the editor role.

The instructions to create a lesson are here: https://make.wordpress.org/training/handbook/lessons/create-the-lesson-on-learn-wordpress-org/

Let me know if you encounter any problems.

[jonathanbossenger]

FYI, for a quick hack, I just copy/paste the markdown from the script into the editor, and it converts it for me 😁