Review exporting a theme - Lesson

[jonathanbossenger]

IMPORTANT

This lesson plan belongs to part of a greater course, Extend a Low Code Block Theme which depends on the completion of Create a Custom Block Theme #1

Please reach out to @jonathanbossenger (Jonathan Bossenger) in the #training team Slack if you would like to help with this lesson plan.

Topic Description

The goal of this lesson is to review the options available to the theme developer for exporting the theme created in the editor.

This lesson will cover exporting template or template part files manually, using the export tool in the editor, as well as using the Create Block Theme plugin.

Objectives

After completing this lesson, participants will be able to:

• Manually export templates or template parts to template files or template parts files
• Use the built-in export tool to export the theme
• Use the create block tool to clone the theme to a new theme

Guidelines

Review the [team guidelines] (https://make.wordpress.org/training/handbook/guidelines/)

Lesson for Review

Exporting Your Block Theme

Review checklist

Reviewers: this is not an extensive list, but it would be helpful if you can keep the following questions in mind while reviewing.

1. Are there any spelling/grammar issues or anything that doesn't make sense?
2. Is the content technically correct?
3. Does the layering of information successfully build from lesson to lesson
4. Can you follow the steps outlined in the course
5. Does the lesson contain enough relevant links to documentation (WordPress documentation, or any other relevant documentation)

[jonathanbossenger]

Draft Lesson - https://github.com/jonathanbossenger/block-theme-course/blob/main/module-01/04-Exporting-theme-files.md

[westnz]

Feedback: Exporting Your Block Theme

• I would suggest listing the 'Site Editor Export Tool' first. Give the good news first :-). When I see the words 'manually', I already feel demotivated.

• Add 'Do:'

• It will be helpful to use annotations to show exactly where the differences are between Before and After:

• Should you not show how to install the zip file onto a new WordPress site, or would everyone at this level know how to do that? Just something worth considering.

Spelling/Punctuation
'Editor and 'Site Editor' in capital letters

[jonathanbossenger]

Thanks for the review feedback @westnz

I would suggest listing the 'Site Editor Export Tool' first. Give the good news first :-). When I see the words 'manually', I already feel demotivated.

That's an interesting viewpoint and one that I fully understand, from a user point of view. However, in my experience, most developers want to know the manual process (understand the underlying tech) and then learn the automated processes. (I at least prefer to know how it works manually, before learning the automated way. Then I fully appreciate how much time the automation is saving me) If it's ok with you, I'll leave this change open, and wait for other comments.

It will be helpful to use annotations to show exactly where the differences are between Before and After:

This is difficult to do using the preformatted code block. I'll take a screenshot of the code editor view and annotate the section to be removed.

Should you not show how to install the zip file onto a new WordPress site, or would everyone at this level know how to do that?

That's a good question, the Create a low code block theme course does have a module on distributing the zip, so the expectation is that the audience for this course will already know how to do this.

[westnz]

Sounds good!

[annezazu]

Finally had time to start reviewing! +1 to the note around "manual" feeling demotivating.

Template parts on the other hand are located in a directory called parts.

In the previous part about templates you note that these were created in earlier lessons. Is the same true for template parts? It feels worth combining/repeating for both.

In general, I'd keep things separate in terms of actions to take in this section, meaning I'd remove mentioning creating a parts folder until the person gets to exporting template parts. It just feels oddly like jumping ahead and it might distract/confuse someone. Feels a bit like "wait why now?!".

Fortunately The Site Editor has an export tool that will export all of your block theme code into an installable theme zip that you can then install on another WordPress site.

"Fortunately, the site editor..." needs to be updated.

Otherwise, I agree with Wes that the obvious solution should be embraced first as it's the smoother way of handling exports and changes. In this case, I might start with the Create block plugin since it's an officially supported option/easiest to follow then move to the Site Editor export tool before finishing discussing manual options.

[jonathanbossenger]

@annezazu thanks for the feedback, I intend to incorporate the changes, but first I'd like to open a discussion around the use of Create Block Theme in this course.

Disclaimer, I love the plugin, and I love what it automates, and as a developer, I love automation. However, as a developer, I also understand that I need to know what the automated process does so that if it ever does something I don't expect, I know what to do. I also need to be aware of any limitations, so that I can find the correct workaround.

I would point out that this course is primarily aimed at developers, not users. If this was a user-focused course, I wouldn't be diving into more "advanced" topics later on.

As I mentioned in a comment on a different lesson, there is also a concern about relying on any external dependencies for the successful completion of this course.

Ideally, it should be, and is, possible for someone to learn block theme development without relying on Create Block Theme. At the present time, Create Block Theme adds tools that will hopefully one day be merged into the Site Editor, but there's no guarantee of that.

My other concern is about what Create Block Theme does not currently do. For example, if I wanted to create any of the secondary or variable templates in the template hierarchy, I have to create the file manually to be able to populate it in the editor.

So because Create Block Theme is both an external dependant, and has current limitations, I'm wary of teaching it first and then showing the manual process. There is a chance that the learner could assume the manual process is not important enough to learn, skip over it, and then come unstuck later on, when understanding the manual process is a requirement.

That having all been said, I'm open to a discussion around this, as I may be on an island here.

[annezazu]

However, as a developer, I also understand that I need to know what the automated process does so that if it ever does something I don't expect, I know what to do. I also need to be aware of any limitations, so that I can find the correct workaround.

Ideally, it should be, and is, possible for someone to learn block theme development without relying on Create Block Theme. At the present time, Create Block Theme adds tools that will hopefully one day be merged into the Site Editor, but there's no guarantee of that.

I totally agree. I think it's fine to lightly mention at the beginning or end as an option but to emphasize the manual approach otherwise! That will also make it easy to remove later if needed when/if the plugin becomes obsolete.

[wparasae]

"However, as a developer, I also understand that I need to know what the automated process does so that if it ever does something I don't expect, I know what to do. I also need to be aware of any limitations, so that I can find the correct workaround... I may be on an island here."

I strongly agree with this rationale. I like Anne's suggestion to lightly mention the tool at the beginning or end, then asking a question like, "Okay, but what is this tool actually doing for us? Let's walk through the manual process so that you understand the full process and can look for any issues that might occur in the future."

Walking this through step by step feels very effective. Your thought process is sound!

Feedback
I love this sentence: "This process is a bit tedious, but it's good to review how to do it, because it helps to understand the structure of the block theme, especially as it pertains to directory structure." Connecting to the 'why' behind why you're doing what you are the way you are is great for adult learners!

I am out of time for today, but I'm going to test out these steps first thing tomorrow. Historically, I have had trouble moving from the site editor's markup to a text editor and having those changes appear in my site, so I'm going to double-check that to discover if this is a "me" thing or not. Stay tuned!

[jonathanbossenger]

Circling back to this:

I would suggest listing the 'Site Editor Export Tool' first. Give the good news first :-). When I see the words 'manually', I already feel demotivated.

I've decided that while it's still a good idea to explain the manual process first, it's also a good idea to highlight the three options at the top of the lesson. So I've added a TL:DR/TOC section at the top, which lists the three options, and includes a link to Create Block Theme.

Then I've added a Summary section at the bottom, which wraps this up with the recommendation to use either the Export option in the Site Editor, or Create Block Theme.

[jonathanbossenger]

https://learn.wordpress.org/lesson/exporting-a-block-theme/