Make WordPress Core

Opened 7 months ago

Closed 7 months ago

Last modified 7 months ago

#39015 closed defect (bug) (fixed)

Customize: custom CSS help link is not helpful

Reported by: celloexpressions Owned by: helen
Milestone: 4.7 Priority: normal
Severity: critical Version: 4.7
Component: Customize Keywords: has-patch commit dev-reviewed
Focuses: docs Cc:


I just realized that the custom CSS help text still points to what was intended as a temporary/placeholder link: https://codex.wordpress.org/Know_Your_Sources#CSS.

There are numerous problems with this link, but the biggest is that it's linking to a place on a page, which causes confusion when users start scrolling through to find what they're looking for (see user testing https://make.wordpress.org/design/2016/11/04/4-7-beta-1-user-testing-in-the-customizer-and-with-twenty-seventeen/). The page is on the Codex and mostly contains a number of links. We can do much better over time, but with the link in core we're currently stuck with this location for building out that documentation.

Can we make a placeholder handbook page for custom CSS for now? Maybe https://developer.wordpress.org/themes/basics/additional-css/? That could move to a user handbook in the future and generally continue to be built out separately from core, but the current link is not in a good place for that documentation to be built out over time. The link is translatable, so this would be a string change; however, putting in 4.7 for now for tracking.

Attachments (1)

39015.diff (955 bytes) - added by helen 7 months ago.

Download all attachments as: .zip

Change History (11)

#1 @georgestephanis
7 months ago

For context, this is the 'help' link that Jetpack adds -- https://en.support.wordpress.com/custom-design/editing-css/

#2 @westonruter
7 months ago

Well, we could copy the page from WordPress.com and put it on WordPress.org, I suppose, with modifications as appropriate if that is OK.

#3 @helen
7 months ago

I don't like the idea of putting this in the developer handbook, even temporarily - if I landed there as a user looking for help I would quickly become confused by the surroundings, even if the content itself was useful to me. I would rather have it still be in the Codex. There's https://codex.wordpress.org/CSS already which may not be a bad place to link to, provided somebody is actually going to work on the documentation part in the next couple days.

#4 @celloexpressions
7 months ago

That particular codex page states:

This article briefly describes the use of CSS in WordPress, and lists some references for further information. For information on CSS itself, see Know Your Sources#CSS.

Which I think is why it wasn't linked to in the first place. In lieu of completely redoing that page for this new purpose, perhaps a page specifically explaining the additional CSS feature and educating users on CSS would make sense. Or, that page could be replaced by what we need here.

#5 @nacin
7 months ago

Let's either decide on https://codex.wordpress.org/CSS or a new https://codex.wordpress.org/Custom_CSS page. I would lean toward a new page. I am *sure* the documentation team (especially everyone at WCUS) can turn something around by release date.

#6 @helen
7 months ago

Right - I get that the link just says "Learn more about CSS" - however, I think for most people a resource on what CSS means for their WP theme is a very good place for users to start exploring the topic. I say we go with codex/CSS which needs updating anyway, and then in the next couple days decide whether to put information about custom/additional CSS directly on that page or link off to a separate one (probably the latter) and do the most important part, which is actually writing/publishing something.

7 months ago

#7 @helen
7 months ago

  • Keywords has-patch commit added; needs-patch removed

#8 @nacin
7 months ago

  • Keywords dev-reviewed added

#9 @helen
7 months ago

  • Owner set to helen
  • Resolution set to fixed
  • Status changed from new to closed

In 39466:

Custom CSS: Change the help link to something better for users.

fixes #39015.

#10 @helen
7 months ago

In 39467:

Custom CSS: Change the help link to something better for users.

fixes #39015 for the 4.7 branch.

Note: See TracTickets for help on using tickets.