Helen Hou-Sandi 10:05 pm on November 18, 2020

Theme previews in the time of blocks

Hello! As you may have seen mentioned in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/., with the help of @dinhtungdu and @dd32 the theme previewer site (wp-themes.com) now shows starter content for the following bundled themes:

Twenty Twenty One (with a little trickery until it’s actually uploaded to the theme directory)
Twenty Twenty
Twenty Seventeen

I understand there may be some confusion about various aspects of this, notably why does this feel like it came out of nowhere and what’s going to happen next, so as the primary driver of this particular effort I’d like to explain the thought process here and open it up for discussion as to what’s next. The summary is: the development happened very quickly over the past week thanks to some availability, it is only for those three bundled themes right now, it is not going to remain limited forever, and there are items to move forward both in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and in the realm of theme development.

It has long been my belief, which I think many share, that the theme previewer site in today’s context does a serious disservice to themes. I also believe that between blocks, blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. patterns, and eventually full site editing, it is more important than ever to the broad success of the WordPress project for themes to showcase their ideal states and make it easier for users to achieve the same thing on their sites. Starter content, introduced in 4.7, was a step in this direction, but has languished for quite some time. I published a post on Make/Core to revisit the concept last month, which is also worth reading, but the important part to consider here is:

since we have a new default theme coming, we should consider what kind of starter content can both showcase the theme in a demo and also help new users get started with block patterns and other fun features – a walkthrough, if you will. Based on experience with starting content, we will want to strike a balance between showing users what they can do and adding too many individual pieces of content that have to be tracked down and removed if they don’t want it.

Also for reference, some priorities I originally outlined for starter content back in 2016:

Not adding (much) to the theme review tasks.
A consistent experience for users as they preview/try out themes.
Encouraging authors to best showcase their themes with content that inspires users, not put them off with advertising.
Potentially be able to teach a bit about using WordPress through that content (e.g. instructions on editing/managing multi-part homepages).
Provide translated/localized content in a sane way, and have a wide enough contributor base that the content is broadly understandable and not (too) culture-specific.

I think if we’re smart about how we choose to implement this, the same content can be used to populate and do some amount of set up for .org previews even in their current state.

Since this is very new and is truthfully a “minimal viable product”, I would like this to remain limited to the bundled themes with starter content for the moment. We need to monitor for its behavior on the live environment, and while this works for the teams behind those particular bundled themes, we need your feedback about your themes to make this both broadly useful and most effectively serve its purpose for users. For instance, using starter content is a part of running this as an MVPMinimum Viable Product "A minimum viable product (MVP) is a product with just enough features to satisfy early customers, and to provide feedback for future product development." - WikiPedia effort, but starter content and demo content may not ideally be the same thing.

Some points of discussion I’d like to seed are:

What have your experiences with starter content been like, both as users and as theme developers?
What has the impact been of starter content on theme reviews?
Are starter content and demo content necessarily the same thing for all or even any themes?
What other content makes sense for the theme previewer site to be displayed for all themes in addition to theme-specific starter content? (See this Meta Trac ticket for more discussion.)
Does it make sense to document a set of best practices surrounding starter content?

+make.wordpress.org/core/

Carolina Nymark 9:57 am on November 19, 2020

What have your experiences with starter content been like, both as users and as theme developers?
As a theme developer, starter content is easy to use and it works well for the purpose of creating example front pages. But I never saw it as intended to be used in place of demo content, so I only focused on that front page.
I have never had an end user ask me what starter content is or how to use it.
But I hear theme developers ask how users are meant to find it, hidden away in the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings..

What has the impact been of starter content on theme reviews?
Today it is minimal. It has no impact. There are about 200 themes in the directory that has starter content, that I am able to find using wpdirectory.net. This list may not be complete.
But the feature is underused because it is only visible on fresh installs.
It depends on if this will be one front page or multiple pages and posts of diverse content. It also depends on how the project lead wants the team to monitor the content.
If the team is expected to stop inappropriate content and there is a large amount of content then it will have a big impact.
Because we will not only be looking at this but also blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. patterns and default content in full site editing themes.

Are starter content and demo content necessarily the same thing for all or even any themes?
No, starter content is meant to help users by letting them replace content instead of starting from a blank page. Demo content shows what the theme can be used for. Some themes have a large amount of different demos.

Does it make sense to document a set of best practices surrounding starter content?
Yes, but not only the starter content and that was something we hoped to be able to discuss on Tuesday.

-I am still thinking about “What other content makes sense”
- Carolina Nymark 10:47 am on November 26, 2020
  
  What other content makes sense
  As Alex touches on below, a style guide with headings and paragraphs to showcase the typography, and the most used blocks.
dingo-d 11:15 am on November 19, 2020

One thing I can say is that I remember adding starter content was super clumsy in the themes. That’s why it never really took off. And I don’t think we should encourage them in the state that they are in today.

Patterns, on the other hand, are simple to implement. Basically copy and paste them from the editor, change any static content URLs and you’re done.

What could be done by the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is an APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. that would generate the preview of the pages based on the registered patterns. Some way to just say in the code, ok for the front page use combination of these patterns:

render_preview_content( 'front_page', [ 'mytheme/jumbotron', 'mytheme/heading', 'mytheme/text-and-images' ] );.

That would then be rendered on the specific pages (basically build a demo using registered patterns).

This does bring us to the most obvious downside of this: who will review it? I can bet that there will be authors who are going to plaster ads, and who knows what kind of content in the patterns. You really cannot review GB code syntax. It’s literally unreadable. So any manual review would go out of the window. The only way to see if there are any issues with it is that you allow the theme (after it passes the review), then later check the preview and if you see a glaring issue, notify the author to fix it.

Reviewing patterns for any kind of violations would be really, really hard.

But I think it’s the easiest way to make previewer useable for authors.
Alex R 12:15 am on November 20, 2020

What have your experiences with starter content been like, both as users and as theme developers?
As a dev, for an extremely long time I didn’t even know WP had first-party starter content and copied the raw HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. from either a third-party WP demo site or from some 2008-ish wp-themes post (the Elements one, IIRC) before I knew that was first-party. The discoverability of WP’s first-party starter content is nearly non-existent, and it took much searching (Google AND Bing!) to even find the relevant entry in the Codex back then. On top of that, I don’t think it’s even been updated to reflect the state of HTML and internet browsers today.

As a user, seeing at least styling of a good chunk of HTML is somewhat indicative to me of how much effort a given theme has given and/or may need to satisfy my theme needs.

More often than not I make child themes of Divi because my primary client has an Elegant Themes developer account for his design business, but I would certainly like to be able to point other themes, free or commercial, to him as starting points or inspirations.

What has the impact been of starter content on theme reviews?
With my primary client at least, appearance is king. He wants to visualize something already existing in use before even considering it as an option, and unless the theme dev has their own demo sites with reasonably representative content he often finds it difficult to grasp what I try to convey to him.

Are starter content and demo content necessarily the same thing for all or even any themes?
I personally think that while they can be similar, there are subtle differences between the two and the comment by Carolina Nymark has a good description of that, where “starter content” is meant to be replaced and “demo content” is meant to be a possibility or ideal. The approach Elegant Themes has used for its Divi Layouts Library previewer takes the “demo content as possibility” mindset to an extreme.

What other content makes sense for the theme previewer site to be displayed for all themes in addition to theme-specific starter content?
For me, a must-have is a single page or post containing as much HTML as can be styled, preferably still in spec and “widely supported” but understandable if an element like `hgroup` sticks around even if it’s not technically in spec anymore.

A nice-to-have would be a showcase of all the built-in guten-blocks with some reasonable fallback for themes that haven’t been updated to support guten-blocks. Admittedly the conditional fallback logic may require non-vanilla coding/a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to accomplish that, but said plugin could also be distributed with the dev-usable starter content package.

Does it make sense to document a set of best practices surrounding starter content?
A best practices list is usually groovy when it’s focused and directed, but since WP-the-product has to accommodate a much more general public than a design agency or firm would have to a more general, less opinionated list would probably be more appreciated overall. In the drive to expand the theme-specific demo/starter content capabilities in the theme directory, maybe offer to theme devs a more standardized place than, e.g., the installation docs to include their own usage guides and best practices to supplement whatever WP-the-product comes up with for themes in general.

Ultimately, the most prominent userbase of WordPress, self-hosted or not, isn’t “devs,” it’s “writers.” Writers want to know that what they write and how they choose to format it are reasonably similar-looking in the backend and frontend, regardless of whether or not they know the difference between the semantics of, e.g., `b` and `strong` in HTML. I had clients who would mark a line of text as “Heading 2” for example because they wanted it to be “big and bold” as easily as possible regardless of whatever custom CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. I put into the theme and WP training I gave them, or use WP’s built-in float-based image alignment and forget to clear the floats later because they weren’t aware (or forgot I told them) that the theme they had offered explicit declaration of a grid of columns or they used to have such a theme active and now they don’t and their old formatting turned into plaintext shortcodes or something.
Joy 2:00 am on November 20, 2020

What have your experiences with starter content been like, both as users and as theme developers?
I’ve never used is as a user. I don’t really see much point in supplying content to users. I have defined it in my theme. I couldn’t set all of my theme options, because it didn’t support array values. I also couldn’t set any options that aren’t in the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., like Media Sizes. It doesn’t make much sense to me to have theme option values in starter content be different from the theme’s default values, and I don’t want to make pages or posts for the user, so I don’t see much point in starter content. I’ve looked at the code, and I’ve heard that starter content takes awhile to parse out, so I made sure it only gets loaded in customizer_preview in my theme.
What has the impact been of starter content on theme reviews?
None, as far as I can see. A lot of reviewers only look at code. If you actually run the theme, you have to try it on a fresh site to make sure it works correctly.
Are starter content and demo content necessarily the same thing for all or even any themes?
They sound very different to me. But then, I don’t understand why anyone wants to put someone else’s content on their site. To me, it seems outside the scope of a theme’s responsibility. I have answered several forum questions why their site doesn’t look like the screenshot or why their site doesn’t have all the images and content of the author’s demo site. Several think the theme is broken because of the discrepancy. I think it’s a bad idea to train users to expect content from a theme.
What other content makes sense for the theme previewer site to be displayed for all themes in addition to theme-specific starter content?
We created new preview content (two different sets) for the previewer, and haven’t gotten them loaded. It makes sense to have a lot of different image sizes, all the various HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. tags, featured images of different sizes, comments. A lot of themes make a home page look different, so a way to see the home page as a blog and as a static page would be great (not that that’s content).
Does it make sense to document a set of best practices surrounding starter content?
Yes. I think the starter content in Twenty Twenty is dreadful, and what I’ve seen of Twenty Twenty One isn’t much better since the user will have to delete the content that the theme adds.

Welcome to the Themes team!

Handbooks and review requirements

Coding standards and plugins

Code Packages

Communication