3.5 Help text changes and improvements

[DrewAPicture]

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.

[nacin]

You're in charge.

[DrewAPicture]

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:

• 22451-dashboard.diff​ - Dashboard (single site)
• 22451-posts.diff​ - Posts & Pages
• 22451-appearance.diff​ - All Appearance screens
• 22451-users.diff​ - Users screens
• 22451-settings.diff​ - Settings screens

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

[DrewAPicture]

Dashboard + Settings

[DrewAPicture]

Dashboard + Appearance + Settings

[DrewAPicture]

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.

[DrewAPicture]

The whole shebang

[DrewAPicture]

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​

[SergeyBiryukov]

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

[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.

[DrewAPicture]

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 :)

[DrewAPicture]

@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.

[DrewAPicture]

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.

[DrewAPicture]

22451.5.diff​:

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

[DrewAPicture]

More tweaks

[DrewAPicture]

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.

[JerrySarcastic]

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.

---

[DrewAPicture]

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.

[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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[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).

[DrewAPicture]

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.

[JerrySarcastic]

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...

[Ipstenu]

Tweaking wp-admin/users.php for Multisite

[Ipstenu]

Making wp-admin/network/users.php match

[Ipstenu]

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)

[Ipstenu]

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...."

[JerrySarcastic]

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. :)

[Ipstenu]

Full Diff

[Ipstenu]

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

Whee :)

[DrewAPicture]

Matching 'Inserting Media' strings for posts and pages

[DrewAPicture]

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 :)

[DrewAPicture]

OK, now we've got it.

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

[Ipstenu]

Correcting typo

[Ipstenu]

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

[nacin]

In 22812:

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

[nacin]

In 22813:

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

[nacin]

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.

[nacin]

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).

[DrewAPicture]

@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.

[Ipstenu]

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 :)

[JerrySarcastic]

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.

[Ipstenu]

We could do it shorter:

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

[JerrySarcastic]

+1 Mika

[nacin]

I can haz a patch?

[Ipstenu]

Nacin can haz

[Ipstenu]

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

[DrewAPicture]

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.

[DrewAPicture]

Media string changes

[DrewAPicture]

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.

[Ipstenu]

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.

[DrewAPicture]

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.

[DrewAPicture]

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

[Ipstenu]

Whoops! "WordPress will automatically turn the it"

Should be "WordPress will automatically turn it"

[DrewAPicture]

Me speak English?

[merty]

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

[nacin]

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.

[DrewAPicture]

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.

[nacin]

In 22925:

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