[Theme Handbook Overhaul] Guides > UI Best Practices

[justintadlock]

This ticket is a part of #816 and will be used for creating new page titled "UI Best Practices" under the Guides chapter.

The content for the new page will be drafted in a Google Doc: https://docs.google.com/document/d/1hkwlJxMSDe8BKb0FEj6_DB6MlY5V8FAWeDqqhmUuVkw/edit?usp=sharing

Note: this is an update of an existing doc.

CC: @alexdeborba

[github-actions]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[github-actions]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[alexdeborba]

I will be responsible for drafting the requested document.

[alexdeborba]

@justintadlock, the document is ready for review and feedback. I appreciate your input so that I can make adjustments, improve, or remove any sections of the document.

[justintadlock]

Awesome, @alexdeborba! I'll get to this as soon as I can this week. I just have a packed schedule, but I've added it to my to-do list.

[justintadlock]

I've been going over this today and looking over the original doc.

Honestly, I'm just not satisfied that either are really about UI. In my mind, when we're talking about UI, I'm thinking more about what the user is seeing on the admin side of WordPress. In classic themes, it was often necessary for themes to output various content in the admin. For block themes, nearly everything is handled by WordPress. So I'm left wondering: Should this doc exist under the Guides chapter?

There is a lot of good advice here, to be sure. However, most of "good" parts are really more about accessibility. And, because we'll have a new accessibility chapter in the handbook (upcoming), I think the best course of action might be to repurpose some of the new work that Alex has done with this doc and use it there.

I don't know yet. I'm just kind of "thinking out loud" at the moment. I need to mull over it, but I'll also leave this for feedback from the handbook reps.

[alexdeborba]

From my perspective, the most challenging aspect of documentation is updating the existing approach when comparing it to the new one. This task involves combining the two approaches while ensuring it remains comprehensible to developers working with classic and block themes. In addition to the difficulties, I believe it has the potential to cause misunderstanding at a given juncture.

In this case, the "old UI" refers to the classic Customizer, while the "new UI" refers to the Block Theme UI. The contrasts between the two are remarkable, both in terms of appearance and approach.

Uncertainty surrounds the document's existence. It would be prudent to establish an archive dedicated explicitly to the traditional themes while simultaneously providing the block theme documentation on the current website (perhaps, I am uncertain). Like you, I am also confronted with this dilemma.

Due to my partial hearing and vision impairment, I naturally understand accessibility. However, I acknowledge that I may have exceeded the intended scope by including areas that may not be necessary. Nevertheless, I am open to repurposing certain parts if they align with the intended purpose.

I am receptive to comments on edits, adding or removing sections, or even rewriting entirely if needed.