Themes: Verify and improve Headstart annotations for the top twenty themes.

[kwight]

Let's make sure that we have valid, functional Headstart annotations for our top twenty themes. Selecting the top twenty themes could be done by various criteria: what's in signup for new users, or /new for existing users, by historic usage, etc.

See: p7DVsv-aHZ-p2#comment-35065

[ianstewart]

I might suggest top 20 themes that aren't Varia child themes. Those themes should all have working Headstart annotations.

[michaeldcain]

If y'all do a quick push on these, I'd be happy to join the fun.

[jordesign]

If part of the process of this is in recreating Home Page layouts using blocks - is this something we could enlist HE help with (the creation of the new sites to be used for the annotations)?

[kwight]

If part of the process of this is in recreating Home Page layouts using blocks - is this something we could enlist HE help with (the creation of the new sites to be used for the annotations)?

That sounds like a great idea, but I'd like the first step to be "these themes all have valid not-broken Headstart annotations" (which I think we can do without hand-crafting block-based homepages first, but maybe I'm missing something?).

[michaeldcain]

I'd like the first step to be "these themes all have valid not-broken Headstart annotations" (which I think we can do without hand-crafting block-based homepages first, but maybe I'm missing something?)

+1. Although it might be nice to open the demo sites and convert the classic blocks to Gutenberg blocks. That was the user isn't met with block warnings when they start the site.

[ianstewart]

the first step to be "these themes all have valid not-broken Headstart annotations"

+1 on this.

If part of the process of this is in recreating Home Page layouts using blocks - is this something we could enlist HE help with (the creation of the new sites to be used for the annotations)?

We might want to do this in the near to medium future though. Opportunities:

• Portfolio Blocks
• Query/Blog Blocks

I think we might run into some blockers with the theme style support for blocks though. (I tried to do this on Tuesday with a few themes.)

[ianstewart]

I noticed yesterday in a usability testing video that some of our demo sites are quite … stuffed. Making not-so-great templates for editing. I'm probably going to go in and trim a few. (Coutoire was a standout.) Don't let that be a blocker though! More wanted to note so I don't forget and also in case anyone sees something simple and wants to do it ad hoc with me. :)

[kathrynwp]

Suggested themes to look at:

From the Recommended Themes List

• [x] Twenty Twenty One
• [x] Twenty Twenty
• [x] Spearhead (being handled in D61382-code)
• [x] Blank Canvas
• [x] Seedlet

Selected Varia child themes

• [x] Varia (doesn't appear you can run Headstart on Varia itself, as it's not intended to be used as a standalone theme)
• [x] Hever
• [x] Coutoire
• [x] Rivington
• [x] Balasana
• [x] Barnsbury
• [x] Dalston
• [x] Exford
• [x] Mayland
• [x] Maywood
• [x] Morden
• [x] Redhill
• [x] Rockfield
• [x] Shawburn
• [x] Stow (We could narrow down the Varia child themes further if need be.)

Older Themes - pulled from the list of top 20 free themes on WP.com

• [x] Radcliffe 2 - (handled in D61599-code)
• [x] Independent Publisher 2 - (handled in D61602-code)
• [x] Dara (handled in D61610-code)
• [x] Edin
• [x] Hemingway Rewritten (handled in D61624-code)
• [x] Karuna - (handled in D61628-code)
• [x] Shoreditch (handled in D61663-code)
• [x] Restaurant (handled in D61755-code)
• [x] Olsen (handled in D61785-code)
• [x] Fortune (handled in D61810-code)

[jordesign]

Thanks @kathrynwp - this is gold!

[ianstewart]

Let's make sure the ones highlighted by @kathrynwp are covered. Here's a top 50 list to expand to …

Top 50 switched-to themes with recommended ones highlighted-

• exford (Recommended)
• shawburn (Recommended)
• morden (Recommended)
• blank-canvas (Recommended)
• seedlet (Recommended)
• twentytwenty (Recommended)
• twentytwentyone (Recommended)
• stow (Recommended)
• redhill (Recommended)
• brompton (Recommended)
• barnsbury (Recommended)
• mayland (Recommended)
• maywood (Recommended)
• rivington (Recommended)
• alves (Recommended)
• coutoire (Recommended)
• rockfield (Recommended)
• balasana (Recommended)
• spearhead (Recommended)
• dara
• hever (Recommended)
• dalston (Recommended)
• baskerville-2 (Recommended)
• lodestar
• stratford (Recommended)
• twentyseventeen
• independent-publisher-2
• dyad-2
• karuna
• apostrophe-2
• scratchpad
• illustratr
• lovecraft
• leven
• twentysixteen
• canard
• ixion
• edda
• argent
• rowling
• rebalance
• penscratch-2
• gateway
• button-2
• twentyeleven
• radcliffe-2
• sketch
• twentyfourteen
• business
• pique

[donalirl]

Suggestion to include Fortune, Venture, Shoreditch, Olsen, and Restaurant as they are popular, and particularly difficult to "manually headstart" (i.e. XML demo import + configuring the Customize settings).

[sixhours]

Going to start this process by activating each of the themes on my sandbox/test sites, running Headstart via CLI, then comparing the result with the corresponding demo site.

[sixhours]

Anything in the above list with a checkbox has been verified as working as expected - ie. the demo site basically matches the Headstart annotation.

Anything without a checkmark needs updating to bring the demo site and the annotation into alignment.

[ianstewart]

Anything in the above list with a checkbox has been verified as working as expected - ie. the demo site basically matches the Headstart annotation.

Worth setting up a separate issue to review the top 20 Headstart annotations for "how editable the output is". For example, Coutoire is just way too long to use as a template. Separating the issues of matching the demo from the quality of the demo as a template?

[sixhours]

Worth setting up a separate issue to review the top 20 Headstart annotations for "how editable the output is". For example, Coutoire is just way too long to use as a template. Separating the issues of matching the demo from the quality of the demo as a template?

Yep! I went with "these themes all have valid not-broken Headstart annotations" as a first step. We can fine-tune things in a future sprint, IMO.

[kwight]

To close this, let's get in decent annotations for @donalirl 's list here too (Fortune, Venture, Shoreditch, Olsen, Restaurant).

[sixhours]

Fortune, Venture, Olsen, Restaurant

@blackjackkent If you end up working on any of these, they're in the /premium repository. I think we have to be more careful with images when generating annotations because they were chosen by the theme authors and we may not have permission to use them across WP.com. We can grab existing images from or upload new ones to the headstartdata.wordpress.com Media Library.

[sixhours]

I started looking at Olsen; the annotations could use a couple more posts to round things out, but otherwise I wouldn't consider it broken:

Featured content gets set, which is one of the bigger issues. We can't use the demo site's images because they're not public domain, so maybe that's causing some confusion. /cc @donalirl in case you had thoughts on Olsen specifically.

[jordesign]

I'll let Donal answer for himself - but perhaps this is one of the instances where the substantial difference between the Demo Site (8BOdR-p2) and annotation is so great that it has the experience of feeling broken.

When the user is expecting something like the demo - the headstarted version looks like it didn't work. I feel like this is a case where we can work on setting a better expectation (perhaps the demo needs to be less full)?

[donalirl]

I think it's fine as long as the overall structure comes through with the headstart. For example with Olsen, as long as the Featured Content Slider, sidebar widgets, and some demo posts come through, that's a great result because the user can get started with that. It doesn't necessarily need to look just like the demo, as long as the overall structure is in place.

The tricky thing for many users is understanding how all the various theme elements and features fit in place. By getting that added to their site, it's much easier for them to go in and play around with the headstarted content, than trying to set up from scratch.

[sixhours]

Heads up, as we're working on annotations going forward, make sure if you're introducing new content to the annotations you're running our spam-flagging unit tests:

1. With the new Headstart annotations applied to your sandbox, run bkismet --type=unit-tests from the theme's parent directory (so if a free theme, from /pub, premium from /premium, although I'm not sure it matters)
2. If you see any failures, see if they're related to your new annotations. That means the copy is not recognized by Bkismet and will flag multiple sites using it as spam.
3. To fix this, you can:
   • Update the annotation to use existing "safe" copy from another theme (themes in /pub are pretty well covered) OR
   • Ping the folks over at cgXQF-p2 to let them know you need new copy added to the spam detector.

[sixhours]

And that's a wrap! In a future sprint we will likely take another look at more themes and demo sites, and make further changes to Headstart annotations to make the Headstart experience better. We can manage all that in a future ticket, since this one's getting unwieldy. :) Closing it out.

[sixhours]

Good to note for posterity, I've also sent all the updated annotations for translation.