WordPress.org

Make WordPress Core

#22451 closed defect (bug) (fixed)

3.5 Help text changes and improvements

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 3.5 Priority: normal
Severity: normal Version: 3.5
Component: Help/About Keywords: has-patch
Focuses: Cc:

Description

There's already been some work on Help text for 3.5 done in the following areas:

  • [22470]: Custom Header / Custom Background color pickers update (Farbastic to Iris)
  • [22388]: Search engine visibility moved to options-reading.php
  • [22380]: Remove XML-RPC help in options-writing.php, hiding Multisite help based on filters
  • [21968]: Moving attachment editing help to new UI in edit-form-advanced.php

I propose going through the screens one-by-one to figure out what needs to be updated, changed, improved, removed, etc.

Patches are welcome.

Attachments (28)

22451-dashboard.diff (2.1 KB) - added by DrewAPicture 18 months ago.
22451-ms-sites.diff (2.4 KB) - added by DrewAPicture 18 months ago.
22451-posts.diff (14.7 KB) - added by DrewAPicture 18 months ago.
22451-appearance.diff (14.5 KB) - added by DrewAPicture 18 months ago.
22451-users.diff (7.4 KB) - added by DrewAPicture 18 months ago.
22451-settings.diff (4.2 KB) - added by DrewAPicture 18 months ago.
22451.diff (6.3 KB) - added by DrewAPicture 17 months ago.
Dashboard + Settings
22451.2.diff (20.8 KB) - added by DrewAPicture 17 months ago.
Dashboard + Appearance + Settings
22451.3-all.diff (38.0 KB) - added by DrewAPicture 17 months ago.
The whole shebang
22451.4.diff (31.2 KB) - added by DrewAPicture 17 months ago.
22451.5.diff (27.9 KB) - added by DrewAPicture 17 months ago.
22451.6.diff (26.8 KB) - added by DrewAPicture 17 months ago.
More tweaks
22451.7.diff (27.2 KB) - added by DrewAPicture 17 months ago.
22451.8.users.diff (1.0 KB) - added by Ipstenu 17 months ago.
Tweaking wp-admin/users.php for Multisite
22451.8.usersnetwork.diff (3.8 KB) - added by Ipstenu 17 months ago.
Making wp-admin/network/users.php match
22451.8.diff (31.1 KB) - added by Ipstenu 17 months ago.
Full Diff
22451.8.2.diff (29.9 KB) - added by DrewAPicture 17 months ago.
Matching 'Inserting Media' strings for posts and pages
22451.9.diff (30.4 KB) - added by DrewAPicture 17 months ago.
22451.9.usersnetwork.diff (3.6 KB) - added by Ipstenu 17 months ago.
Correcting typo
22451.9.sites.diff (3.0 KB) - added by Ipstenu 17 months ago.
Fixing the sites page. Bold columns doesn't exist. Also bad verbiage that was wrong.
22451.10-all.diff (34.6 KB) - added by DrewAPicture 17 months ago.
22451-edit-form-advanced.1.diff (1.6 KB) - added by Ipstenu 17 months ago.
Nacin can haz
22451-embeds.diff (1.7 KB) - added by DrewAPicture 17 months ago.
22451.11.diff (2.1 KB) - added by DrewAPicture 17 months ago.
Media string changes
22451.11.2.diff (2.1 KB) - added by DrewAPicture 17 months ago.
22451.11.3.diff (2.1 KB) - added by DrewAPicture 17 months ago.
Me speak English?
22451.11.4.diff (2.1 KB) - added by merty 17 months ago.
"click the..." is better than "click on the"
22451.3.diff (1.9 KB) - added by nacin 17 months ago.

Download all attachments as: .zip

Change History (82)

comment:1 SergeyBiryukov18 months ago

  • Milestone changed from Awaiting Review to 3.5

comment:2 nacin18 months ago

  • Owner set to DrewAPicture
  • Status changed from new to assigned

You're in charge.

comment:3 nacin18 months ago

  • Keywords audit added

DrewAPicture18 months ago

DrewAPicture18 months ago

comment:4 DrewAPicture18 months ago

  • Keywords has-patch added

OK. I've gone through every single-site Dashboard page and made up some patches for suggested Help text changes. In all but the *-settings.diff patch, I added proper coding standards spacing to the Help text blocks I happened to be changing.

Since not a lot has changed in terms of the Network Admin, I propose we re-organize and/or spruce up those Help tabs in 3.6-early. Most of it is just poor organization and text that could use a refresh. So please disregard 22451-ms-sites.diff.

Also of note, I added new 'Inserting Media' tabs to the Posts and Pages add new screens as well as reorganized the Publish settings tab for Posts.

Patches:

I decided to keep the patches separated by section until there's more consensus on what's what.

Last edited 18 months ago by DrewAPicture (previous) (diff)

comment:5 JerrySarcastic18 months ago

  • Cc fittingsites@… added

comment:6 Ipstenu17 months ago

  • Cc ipstenu@… added

comment:7 mercime17 months ago

  • Cc mercijavier@… added

comment:8 karmatosed17 months ago

  • Cc karmatosed added

comment:9 rachelbaker17 months ago

  • Cc rachelbaker added

DrewAPicture17 months ago

Dashboard + Settings

DrewAPicture17 months ago

Dashboard + Appearance + Settings

comment:10 DrewAPicture17 months ago

I'd say 22451.2.diff is ready to go, it knocks out 3/5. Most of it just typo fixes and emphasis-added stuff.

I'm hoping to get extra eyes on the new 'Inserting Media' tabs I added to two different pages in the remaining patches.

DrewAPicture17 months ago

The whole shebang

comment:11 DrewAPicture17 months ago

OK, so I realize this ended up being kind of a mess (sorry).

I've rolled everything into a single patch and removed the unnecessary respacing so it's much easier to see what's been changed.

22451.3-all.diff

comment:12 SergeyBiryukov17 months ago

22451.3-all.diff has a typo in wp-admin/themes.php, line 45: &#822 should be &#8221.

comment:13 follow-ups: nacin17 months ago

Looking at -all.diff, we don't need to capitalize everything that may be considered "proper" when it works just fine as a lowercase word. Otherwise, it feels a bit too formal, like we're a Terms of Service ("the Company") or an up-tight technical manual.

comment:14 in reply to: ↑ 13 DrewAPicture17 months ago

Replying to nacin:

Looking at -all.diff, we don't need to capitalize everything that may be considered "proper" when it works just fine as a lowercase word. Otherwise, it feels a bit too formal, like we're a Terms of Service ("the Company") or an up-tight technical manual.

I mostly just attempted to clarify some things and follow the general style @jane sort of loosely followed.

It's all certainly open for discussion :)

DrewAPicture17 months ago

comment:15 DrewAPicture17 months ago

@SergeyBiryukov: Nice catch on the typo! 22451.4.diff removes some of the extra capitalizations which also makes for a tighter patch. Not really sure what to do about making some of the strings less "formal" though, a lot of that stuff was already in there.

Last edited 17 months ago by DrewAPicture (previous) (diff)

comment:16 in reply to: ↑ 13 DrewAPicture17 months ago

Replying to nacin:

Otherwise, it feels a bit too formal, like we're a Terms of Service ("the Company") or an up-tight technical manual.

Can you be a little more specific about what you're referring to as "formal"? I've only introduced about 5 new strings, most of the procedural stuff was already there.

Here's what's already on my radar:

  • The oEmbed string in edit-form-advnaced is a bit much. That's getting chopped and/or tacked on to Add Media.
  • The new DFW string (also edit-form-advanced) was all part of a veritable paragraph on the Post Editor that I broke into two pieces. I'll look at making it simpler and pointing out to Codex for more info.
  • There's a big procedural set of instructions in theme-editor that was already there. All that was fixed there was proper string concatenation.

DrewAPicture17 months ago

comment:17 DrewAPicture17 months ago

22451.5.diff:

  • Shortened the oEmbed bits for posts and pages
  • Shortened the DFW description
  • Left the concat changes in theme-editor.php out.

DrewAPicture17 months ago

More tweaks

comment:18 DrewAPicture17 months ago

Most of the changes are semantics, grammar fixes and the like. However, there are a few new strings that I was hoping for input on.

– On the new post screen:

Add Media - You can upload and insert media (images, galleries, audio, etc.) by clicking the Add Media button above the Post Editor and following the directions.

Embed Media - The post editor also supports embedding media via oEmbed from sites like Twitter, YouTube and others. Please refer to the Codex for a full list of supported providers.

and

Distraction-Free Writing - This fullscreen editor lets you focus on just that, writing distraction-free. Click the Fullscreen icon in Visual mode or the Fullscreen button in Text mode.

– On the new page screen:

Inserting Media - Just as with posts, you can upload and insert media (images, galleries, audio, etc.) by clicking the Add Media button above the Page Editor and following the directions. You can also embed media via oEmbed from sites like Twitter, YouTube and others. Please refer to the Codex for full list of supported providers.

comment:19 follow-ups: JerrySarcastic17 months ago

These should definitely be in contextual help; I'm shocked they're not already.

Because the funtionality is no different when adding a page or adding a post, I would think you could use the same text for both help sections. Instead of writing a unique string titled Inserting Media on the contextual help for "Pages", you could just re-use the text strings for Add Media, Embed Media, and Distraction-Free Writing since the actions are the same, but better explained as separate strings

For Embedding Media, I think a quick sentence explaining how to do actually do it (i.e., paste the media URL) will provide a nice hint, since there is not dedicated button for for oEmbeds.


Embed Media - With oEmbed, you can easily media from popular websites such as Twitter, YouTube, Instagram, Slideshare, and others. All you need to do is copy the URL of that media, and paste it directly into the text of your page/post. To learn more about oEmbeds and ​see a full list of supported providers, please refer to the Codex.


comment:20 in reply to: ↑ 19 DrewAPicture17 months ago

Replying to JerrySarcastic:

Because the funtionality is no different when adding a page or adding a post, I would think you could use the same text for both help sections. Instead of writing a unique string titled Inserting Media on the contextual help for "Pages", you could just re-use the text strings for Add Media, Embed Media, and Distraction-Free Writing since the actions are the same, but better explained as separate strings

That's good thinking, and I'm sure the translators would be glad to have the fewer strings.

For Embedding Media, I think a quick sentence explaining how to do actually do it (i.e., paste the media URL) will provide a nice hint, since there is not dedicated button for for oEmbeds.

A couple of iterations ago in 22451.4.diff, there was a longer version that I cut shorter. I like where you've gone with your version, so what about something like this:

  • Embed Media - With oEmbed, you can easily embed media from popular websites such as Twitter, YouTube, Instagram, SoundCloud, and others. All you need to do is copy the URL of that media, and paste it directly into the text of your page/post. Please refer to the Codex to learn more about oEmbeds.

comment:21 in reply to: ↑ 19 ; follow-ups: SergeyBiryukov17 months ago

Replying to JerrySarcastic:

All you need to do is copy the URL of that media, and paste it directly into the text of your page/post.

"Make sure that the URL is on its own line and not hyperlinked" (from the Codex page) is also an important part, perhaps it should be mentioned in some form.

comment:22 in reply to: ↑ 21 DrewAPicture17 months ago

Replying to SergeyBiryukov:

"Make sure that the URL is on its own line and not hyperlinked" (from the Codex page) is also an important part, perhaps it should be mentioned in some form.

So maybe this:

  • Embed Media - With oEmbed, you can easily embed media from popular websites such as Twitter, YouTube, Instagram, SoundCloud, and others. All you need to do is copy the URL of that media, and paste it directly into the text of your page/post on its own line. Please refer to the Codex to learn more about oEmbeds.
Last edited 17 months ago by DrewAPicture (previous) (diff)

DrewAPicture17 months ago

comment:23 DrewAPicture17 months ago

Thanks @JerrySarcastic and @SergeyBiryukov!

22451.7.diff duplicates the Add Media/Embed Media strings for both posts and pages and replaces the Embed Media string with the reworked version.

comment:24 follow-up: SergeyBiryukov17 months ago

  • Maybe "learn more about oEmbed" (vs. oEmbeds), since the protocol name is singular.
  • Or <a href="http://codex.wordpress.org/Embeds">learn more about Embeds</a> (without the anchor).

comment:25 in reply to: ↑ 24 DrewAPicture17 months ago

Replying to SergeyBiryukov:

  • Maybe "learn more about oEmbed" (vs. oEmbeds), since the protocol name is singular.
  • Or <a href="http://codex.wordpress.org/Embeds">learn more about Embeds</a> (without the anchor).

Do you want to update the patch? I'm on the go.

comment:26 in reply to: ↑ 21 ; follow-up: JerrySarcastic17 months ago

Replying to SergeyBiryukov:

Replying to JerrySarcastic:

All you need to do is copy the URL of that media, and paste it directly into the text of your page/post.

"Make sure that the URL is on its own line and not hyperlinked" (from the Codex page) is also an important part, perhaps it should be mentioned in some form.

I agree, that's a good add. I don't know if new users will instinctively "get it" without reading a bit more documentation, but it's a pretty complete synopsis of how to do an oEmbed.

I think it might not be a bad idea to add a little "hint" ext into the Add Media section to help people figure out the new gallery functionality as well. At this point it is basically a hidden feature since it's not immediately clear how to create a gallery (if you're a new user, anyway)

Something like this?

Add Media - You can upload and insert media (images, audio, document files, etc.) by clicking the Add Media button. Select from images and files already uploaded to the Media Library, or upload new media to add to your page or post. To create an image gallery, simply select multiple images to add.

It's not perfect (in lieu of more complete documentation) but it's a start...

Ipstenu17 months ago

Tweaking wp-admin/users.php for Multisite

Ipstenu17 months ago

Making wp-admin/network/users.php match

comment:27 Ipstenu17 months ago

Looking at the latest patch, the change for Multisite in users.php should specify that 'remove' doesn't delete the user from the network. That made me check the changes in language on the network users page and yiiiikes!

Included in my patches are a slight change to wp-admin/users.php (removing from a site doesn't remove from the network) and a re-do of multisite's wp-admin/network/users.php (bringing it in-line with how single users.php looks)

comment:28 in reply to: ↑ 26 ; follow-up: Ipstenu17 months ago

Replying to JerrySarcastic:

Add Media - You can upload and insert media (images, audio, document files, etc.) by clicking the Add Media button. Select from images and files already uploaded to the Media Library, or upload new media to add to your page or post. To create an image gallery, simply select multiple images to add.

Shouldn't that be "You can select from the images and files already upload...."

comment:29 in reply to: ↑ 28 JerrySarcastic17 months ago

Replying to Ipstenu:

Shouldn't that be "You can select from the images and files already upload...."

They both work; it's a matter of style. But I think it's clearer (or "friendlier") the way you stated it, so that's good by me. :)

Last edited 17 months ago by JerrySarcastic (previous) (diff)

Ipstenu17 months ago

Full Diff

comment:30 Ipstenu17 months ago

Okay, I updated the master diff with those changes and uploads v 8.

Whee :)

DrewAPicture17 months ago

Matching 'Inserting Media' strings for posts and pages

comment:31 DrewAPicture17 months ago

I'd say we have a good patch in 22451.8.2.diff. Thanks @ipstenu for the upload string changes and everybody for the feedback and suggestions :)

DrewAPicture17 months ago

comment:32 DrewAPicture17 months ago

OK, now we've got it.

22451.9.diff rolls in @ipstenu's 22451.8.users.diff and 22451.8.usersnetwork.diff.

Ipstenu17 months ago

Correcting typo

Ipstenu17 months ago

Fixing the sites page. Bold columns doesn't exist. Also bad verbiage that was wrong.

DrewAPicture17 months ago

comment:33 DrewAPicture17 months ago

  • Keywords commit added

comment:34 nacin17 months ago

In 22812:

Fix various typos and omissions across a number of help tabs. props DrewAPicture, Ipstenu. see #22451.

comment:35 nacin17 months ago

In 22813:

Updates to post.php help text for posts and pages, including a new section on inserting media. props DrewAPicture, Ipstenu. see #22451.

comment:36 follow-up: nacin17 months ago

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

A few things seemed off about the new media strings, so I didn't yet offer them for translation:

  • We don't actually refer to oEmbed as oEmbed anywhere. We call them Embeds (in the Codex page, when they had settings on options-media.php, etc.). But we refer to it as oEmbed two or three times here. (Also, I would probably include Flickr over Instagram at this time.)
  • "document files" -> "documents", I imagine?
  • "To create an image gallery, simply select multiple images to add." Well, it's not so simple, because they then need to insert the gallery (maybe after changing its settings). Perhaps "start by selecting multiple images to add" and then lead them on their way? Or remove the line.

comment:37 nacin17 months ago

A number of changes were not included in [22812] and [22813]. Translators have less than two weeks, I'd rather not break so many large strings for enhancements or stylistic tweaks. (The wp-admin/themes.php diff is inconsistent. In some cases, straight quotes are removed. In other cases, curly quotes are added. What's it going to be?) We can deal with these in 3.6.

I was going to add some of the network help, but then I realized one of them was a re-styling, and the other one added a note about wildcards, when wildcard limitations were actually scaled back some versions ago to only affect large networks (more than 10k users or sites).

comment:38 DrewAPicture17 months ago

@nacin, thanks for the feedback and initial commits. I'll start reworking the media strings in the next couple days and see if we can't add a little more clarity and consistency.

comment:39 Ipstenu17 months ago

It's no big loss to dump the wildcard comments, but as it stands right now, we have totally wrong info for networks. We reference 'bold headers' where there are none, among others. The restyling was to bring it in line with the non-network users, but that too can be dropped if that's better.

I'd still like to see the single site users mention that we don't remove you from the network (22451.8.users.diff) since that comes up often enough.

Would it be better to recombine 22451.9.usersnetwork.diff into one section and remove wildcard, or start over? Either way can work :)

comment:40 in reply to: ↑ 36 JerrySarcastic17 months ago

Replying to nacin:

  • "To create an image gallery, simply select multiple images to add." Well, it's not so simple, because they then need to insert the gallery (maybe after changing its settings). Perhaps "start by selecting multiple images to add" and then lead them on their way? Or remove the line.

Perhaps something more explicit like:

Add Media - You can upload and insert media (images, audio, document files, etc.) by clicking the Add Media button. Select from images and files already uploaded to the Media Library, or upload new media to add to your page or post. To create an image gallery, start by selecting multiple images to add, and then click on the "Create a new gallery" button.

comment:41 Ipstenu17 months ago

We could do it shorter:

"To create an image gallery, select the images to add and click on the "Create a new gallery" button."

comment:43 nacin17 months ago

  • Keywords audit removed

I can haz a patch?

Ipstenu17 months ago

Nacin can haz

comment:44 Ipstenu17 months ago

22451-edit-form-advanced.1.diff​ for ya, Nacin. That was the one place I could still find it on a fresh SVN

DrewAPicture17 months ago

comment:45 DrewAPicture17 months ago

  • Keywords has-patch added; needs-patch removed

22451-embeds.diff reworks the Embed Media string. It removes 'oEmbed' references, replaces Instagram with Flickr and simplifies the procedural bits.

FROM:

Embed Media - With oEmbed, you can easily embed media from popular websites such as Twitter, YouTube, Instagram, SoundCloud, and others. All you need to do is copy the URL of that media, and paste it directly into the text of your page/post on its own line. Remember to make sure that the URL is on its own line and not hyperlinked. Please refer to the Codex to learn more about oEmbed.

TO:

Embed Media - You can embed media from many popular websites including Twitter, YouTube, Flickr, SoundCloud and others. Simply copy and paste the media URL into the text of your post/page and make sure it is on its own line and not hyperlinked. WordPress will automatically turn the URL into a media embed when the post/page is viewed on your site. Please refer to the Codex to learn more about embeds.

Last edited 17 months ago by DrewAPicture (previous) (diff)

DrewAPicture17 months ago

Media string changes

comment:46 DrewAPicture17 months ago

22451.11.diff contains media string changes following [22813].

Incorporates @Ipstenu's changes in 22451-edit-form-advanced.1.diff, changing 'document files' to 'documents' from comment:36, and 22451-embeds.diff.

comment:47 follow-up: Ipstenu17 months ago

Re-reading the embed, and it's an imcomplete sentence.

"Simply copy and paste the media URL into the text of your post/page and make sure it is on its own line and not hyperlinked."

That's not good.

How about this?

You can embed media from many popular websites including Twitter, YouTube, Flickr, SoundCloud and others by pasting the media URL into the content of your post/page. Just make sure it is on its own line and not hyperlinked, and WordPress will automatically turn the URL into a media embed when the post/page is viewed. Please refer to the Codex to ​learn more about embeds.

comment:48 in reply to: ↑ 47 DrewAPicture17 months ago

Replying to Ipstenu:

I feel like 'it' and 'URL' should be switched in the second sentence. How about this:

You can embed media from many popular websites including Twitter, YouTube, Flickr, SoundCloud and others by pasting the media URL into the content of your post/page. Just make sure the URL is on its own line and not hyperlinked, and WordPress will automatically turn the it into a media embed when the post/page is viewed. Please refer to the Codex to ​learn more about embeds.

DrewAPicture17 months ago

comment:49 DrewAPicture17 months ago

DrewAPicture> I switched 'it' and 'URL' in the second sentence. Reads a little cleaner.
<ipstenu> Awesome :D
<ipstenu> High fives for us!

22451.11.2.diff

comment:50 Ipstenu17 months ago

Whoops! "WordPress will automatically turn the it"

Should be "WordPress will automatically turn it"

DrewAPicture17 months ago

Me speak English?

merty17 months ago

"click the..." is better than "click on the"

comment:51 merty17 months ago

  • Cc merty92@… added

nacin17 months ago

comment:52 follow-up: nacin17 months ago

22451.3.diff — I wanted to simplify this a bit.

We said this on the about page in 3.4: "Just paste a tweet URL on its own line." If they don't catch on, we've linked them to the Codex as well.

Also, "Add Media" is the name of the button, yes, but as a concept, it is a superset that includes "Embed Media". These should probably not be distinct sections, lest we confuse the user what "Add" means veruss what "Embed" means. Here's my simplified take.

comment:53 in reply to: ↑ 52 DrewAPicture17 months ago

Replying to nacin:

22451.3.diff looks good to me. It's almost too simple, but as you said, we're linking them to the Codex so if they don't get it there's more info readily available.

comment:54 nacin17 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 22925:

Media help. props DrewAPicture, merty, Ipstenu. fixes #22451.

Note: See TracTickets for help on using tickets.