Better wording for the help tab on Edit Page screen

[timph]

line 329 of edit-form-advanced.php:
'<p>' . __('Creating a Page is very similar to creating a Post, and the screens can be customized in the same way using drag and drop, the Screen Options tab, and expanding/collapsing boxes as you choose. This screen also has the distraction-free writing space, available in both the Visual and Text modes via the Fullscreen buttons. The Page editor mostly works the same as the Post editor, but there are some Page-specific features in the Page Attributes box:') . '</p>';

It displays the following text:

Creating a Page is very similar to creating a Post, and the screens can be customized in the same way using drag and drop, the Screen Options tab, and expanding/collapsing boxes as you choose. This screen also has the distraction-free writing space, available in both the Visual and Text modes via the Fullscreen buttons. The Page editor mostly works the same as the Post editor, but there are some Page-specific features in the Page Attributes box:

The first sentence doesn't make much sense to me. I believe it might be saying something along the lines of:

"Creating a Page is very similar to creating a Post, and the screens can be customized just like the Screen Options tab. You can drag and drop them, and expand/collapse the boxes as you choose."

The colon at the end leads me to believe there's something more to show. I believe this should be a period instead of a colon.

I think this section would read better to those who use the help feature like this:

"Creating a Page is very similar to creating a Post, and the screens can be customized just like the Screen Options tab. You can drag, drop, expand and collapse the boxes as you choose. This screen also has the distraction-free writing space, which is available in both the Visual and Text modes via the Fullscreen buttons. The Page editor works the same as the Post editor, but there are some Page-specific features in the Page Attributes box."

I propose that line 329 of edit-form-advanced.php be changed to this:

'<p>' . __( 'Creating a Page is very similar to creating a Post, and the screens can be customized just like the Screen Options tab. You can drag, drop, expand and collapse the boxes as you choose. This screen also has the distraction-free writing space, which is available in both the Visual and Text modes via the Fullscreen buttons. The Page editor works the same as the Post editor, but there are some Page-specific features in the Page Attributes box.' ) . '</p>';

The file as a whole doesn't fall consistent with the WordPress coding standards as well. I noticed there's several areas where spaces aren't placed when functions are opened and closed between the parentheses and single quotes. For example lines 355-357, as well as line 329 that I'm writing about.

[valendesigns]

Can't do anything about this now. We are in a string freeze.

[sjmur]

Howdy,

Looking to get started on WP Core. Want to take this as my first little contrib to the platform if permitted.

[netweb]

Our handbook is a good place to start:

​https://make.wordpress.org/core/handbook/contribute/

[marutim]

Seems got late by some 50 minutes. Incase @sjmur changes his minds, I call Dibs :)

[sjmur]

Replying to netweb:

Our handbook is a good place to start:

​https://make.wordpress.org/core/handbook/contribute/

Great. I'll get the env set up and take a look into patching the above.

[sjmur]

Patch file

[sjmur]

Replying to netweb:

Our handbook is a good place to start:

​https://make.wordpress.org/core/handbook/contribute/

Thanks for this. I've attached my patch file to this bug. What's next!

[netweb]

Replying to sjmur:

Thanks for this. I've attached my patch file to this bug. What's next!

@sjmur Thanks, the patch looks good as in what the patch should look like with the proposed text :)

I'm adding "2nd-opinion" here as a 2nd opinion on the proposed text change would be welcome.

I'm personally in favour of leaving the original string as is, it makes sense to me now that I've actually taken the time to read it concisely, the one change I would suggest is to indeed switch from a colon : and the end of the sentence to a period/full stop ., but that one change would be the only change.

---

Replying to timph:

The first sentence doesn't make much sense to me. I believe it might be saying something along the lines of:

"Creating a Page is very similar to creating a Post, and the screens can be customized just like the Screen Options tab. You can drag and drop them, and expand/collapse the boxes as you choose."

That is incorrect, that is NOT what it is trying to say.

The original sentence: "Creating a Page is very similar to creating a Post, and the screens can be customized in the same way using drag and drop, the Screen Options tab, and expanding/collapsing boxes as you choose."

What this is saying is that both the Posts and Pages screens can be customized the same way, both can use drag and drop, both can expand and collapse boxes, and both can be further customized by changing the values/configuration in the "Screen Options" tab.

[timph]

I agree with @netweb on the verbiage after rereading this again, but it would lead me back to the point I was attempting to make - that it could be worded better. If it takes a group of people rereading it several times for comprehension, then it's probably not conveying the message it should in the best possible way.

The section "the Screen Options tab" seems more apparent now that it's meant to be more of a parenthetical expression. It mislead me when reading it from a contextual point of view without actually paying attention to what was being said. It's like a list of adverb phrases with a parenthetical expression interrupting it. From just a 'style' standpoint - I'd usually say to try to use some -'s as they are a more forceful way to separate out a parenthetical expression in the middle of a list. Overuse of commas can be confusing to those who use automated readers that might have extended pauses in between each comma thinking it's a list - much as I did!

Original:

Flesch-Kincaid Reading Ease 55.3 - Grade Level 14.2
Creating a Page is very similar to creating a Post, and the screens can be customized in the same way using drag and drop, the Screen Options tab, and expanding/collapsing boxes as you choose.

Revised:

Flesch-Kincaid Reading Ease 71.6 - Grade Level 7.2:
Creating a Page is very similar to creating a Post. You can use the Screen Options tab to customize the screens using drag and drop, and expanding/collapsing them as you choose.

Flesch-Kincaid tests, while not overly accurate, are a good reference point - at the very least. A general target audience should fall below grade level 8 to be considered easy to read to the vast majority.

[sjmur]

Replying to timph:

I agree with @netweb on the verbiage after rereading this again, but it would lead me back to the point I was attempting to make - that it could be worded better. If it takes a group of people rereading it several times for comprehension, then it's probably not conveying the message it should in the best possible way.

The section "the Screen Options tab" seems more apparent now that it's meant to be more of a parenthetical expression. It mislead me when reading it from a contextual point of view without actually paying attention to what was being said. It's like a list of adverb phrases with a parenthetical expression interrupting it. From just a 'style' standpoint - I'd usually say to try to use some -'s as they are a more forceful way to separate out a parenthetical expression in the middle of a list. Overuse of commas can be confusing to those who use automated readers that might have extended pauses in between each comma thinking it's a list - much as I did!

Original:

Flesch-Kincaid Reading Ease 55.3 - Grade Level 14.2
Creating a Page is very similar to creating a Post, and the screens can be customized in the same way using drag and drop, the Screen Options tab, and expanding/collapsing boxes as you choose.

Revised:

Flesch-Kincaid Reading Ease 71.6 - Grade Level 7.2:
Creating a Page is very similar to creating a Post. You can use the Screen Options tab to customize the screens using drag and drop, and expanding/collapsing them as you choose.

Flesch-Kincaid tests, while not overly accurate, are a good reference point - at the very least. A general target audience should fall below grade level 8 to be considered easy to read to the vast majority.

Interesting take on this. As someone on the outside looking in I would have to agree that the original script had myself puzzled on the first read. The 2nd take is my preference and has my vote to be added. It's far easier to understand and for the broad audience we support, it is the best solution, in my opinion.

[sjmur]

Side note, how does one assign this ticket to themselves? Or does a maintainer have to assign it to the person?

Also this is delegated for 4.4, Are string changes frozen for the lifetime of the release? Only core security fixes for the x.x.1 releases?

[sjmur]

Replying to valendesigns:

Can't do anything about this now. We are in a string freeze.

Is this patch good to go? No replies on this ticket for some time

[SergeyBiryukov]

Replying to timph:

Flesch-Kincaid Reading Ease 71.6 - Grade Level 7.2:
Creating a Page is very similar to creating a Post. You can use the Screen Options tab to customize the screens using drag and drop, and expanding/collapsing them as you choose.

That's not what it's trying to say either. Screen Options tab only allows you to show or hide specific meta boxes. It's just another way of customizing, in addition to drag and drop and expanding/collapsing meta boxes.

The original sentence could probably be phrased better in some other way, but it's still the most accurate. I would only remove the colon at the end, which was accidentally introduced in [18779].

[SergeyBiryukov]

Replying to sjmur:

Side note, how does one assign this ticket to themselves? Or does a maintainer have to assign it to the person?

See ​https://make.wordpress.org/core/handbook/contribute/trac/#roles for details.

Also this is delegated for 4.4, Are string changes frozen for the lifetime of the release? Only core security fixes for the x.x.1 releases?

Yes, we don't generally introduce new strings in minor releases, as that would mean unexpected work for translators.

[sjmur]

Replying to SergeyBiryukov:

Replying to sjmur:

Side note, how does one assign this ticket to themselves? Or does a maintainer have to assign it to the person?

See ​https://make.wordpress.org/core/handbook/contribute/trac/#roles for details.

Also this is delegated for 4.4, Are string changes frozen for the lifetime of the release? Only core security fixes for the x.x.1 releases?

Yes, we don't generally introduce new strings in minor releases, as that would mean unexpected work for translators.

Thanks for the feedback! I understand now what ownership means on WP.

I never thought about the l10n aspect, makes sense! Cheers!

[netweb]

Replying to SergeyBiryukov:

The original sentence could probably be phrased better in some other way, but it's still the most accurate. I would only remove the colon at the end, which was accidentally introduced in [18779].

+1 on this, which is the same as I wrote:

Replying to netweb:

I'm personally in favour of leaving the original string as is, it makes sense to me now that I've actually taken the time to read it concisely, the one change I would suggest is to indeed switch from a colon : and the end of the sentence to a period/full stop ., but that one change would be the only change.

@sjmur, if you want to refresh the patch to just change the colon : to a period/full stop . we will go with the same original text but changing only the punctuation :)

[manolis09]

Also starting on WP Core, currently at WC CH. I thought to begin with this small change, replacing the colon with the full stop. Please advice if I should have done anything differently.

[sjmur]

Sorry folks, Was travelling and only getting back to this now.

I see @manolis09 supplied the colon to full stop change. Are we good to go on this?

[SergeyBiryukov]

In 34594:

Replace a stray semicolon on Edit Page screen with a full stop.

Props manolis09, sjmur.
Fixes #33297.