Improve copy of first post to provide useful info and tips

[demetris]

As agreed in the IRC dev meeting of 22 October 2009, we can improve the text of the first post to offer useful information, tips, and hints, like a link to subcribe to update notifications (and a sentence on why they are important).

Since we are not in string-freeze yet, I think this could go into 2.9; it won’t break anything.

[demetris]

New Hello World! post for 2.9, first draft

[demetris]

I’m attaching a first draft of the new Hello World! post.

A live version is here: ​http://op109.net/176/wp-29-hello-world

The copy is also available and editable in Etherpad: ​http://op111.etherpad.com/3

Please, be kind enough to offer your thoughts.

[demetris]

New Hello World! post for 2.9, draft, after some polishing by Jane

[filosofo]

I like what you've done overall. The following thoughts are nitpicky, but this content will be read by millions.

This is the first post of your website, generated automatically,

This is obvious and unnecessary information. How about just "This first post contains important information"?

The combined emphasis and boldface in this phrase should be re-thought:

contains important and useful information

Either emphasize the entire phrase or just the key words. The combination is unnecessary and seems condescending. Also, why do we need to say both "useful" and "important"? Is there content that is one but not the other?

Subscribe to the WordPress mailing list for update notifications

It doesn't make sense to have a <ul> with just one item: in that case it's not really a list. If you just mean to emphasize this sentence then use <em> tags or the like.

This will help you keep your WordPress site secure and up-to-date

"This" is somewhat vague. How about "The notification list informs you how to secure and update your WordPress site."

For the "enjoying the WordPress experience" list, "in" is not the right preposition. "Users › Your Profile" either describes navigation hierarchy (in which one one item is under another) or a web page's location, which usually has information on it.

Also, it would be better to put first the actions that are important to the user:

"Edit your personal information on the Users › Your Profile page."

The "start publishing" action item should be in the first couple of list items, as it's presumably the reason someone set up WordPress.

How about a link to the support forums? Could we link the action items to their corresponding Codex pages?

[demetris]

New Hello World! post for 2.9, revision 4, with thanks to filosofo

[demetris]

New revision is up. Now with more signal and less noise, thanks to filosofo’s help.

See formatted text here: ​http://op109.net/184/wp-29-hello-world-r004-filosofo-edition

Editable copy at: ​http://op111.etherpad.com/3

Replying to filosofo:

Subscribe to the WordPress mailing list for update notifications

It doesn't make sense to have a <ul> with just one item: in that case it's not really a list. If you just mean to emphasize this sentence then use <em> tags or the like.

My intention was to emphasize, yes. And I would not like to put a whole sentence of linkable text within strong or em tags.

But another reason I made it like this is that I’m thinking of it as the first and most important item in a todo list which is briefly interrupted for a quick explanation, and then resumes.

To put it another way, if I used an ordered list, I would start the other part like this:

<ol start="2">

BTW, HTML5 brought back the start attribute, which makes me happy! :-D

Does this make any sense? If it doesn’t, let’s change it.

For the "enjoying the WordPress experience" list, "in" is not the right preposition. "Users › Your Profile" either describes navigation hierarchy (in which one one item is under another) or a web page's location, which usually has information on it.

I switched the parts of the items around, but I’m having trouble with the prepositions. Now that the parts are reversed, “at” sounds better than “on” to me. Don’t know...

But I like the reversed scheme, because it allows dropping the repetitive “You can”.

How about a link to the support forums? Could we link the action items to their corresponding Codex pages?

I thought about the Codex myself when making the first draft. But I don’t like the idea of linking to the forums — let people go to the Codex and read first, and, if they cannot find help there, the forums are one click away.

I also thought about linking the action items, but to their admin URLs, not to the Codex. (Printing the links after checking for capabilities.)

Is this a bad or a good idea?

(I did not try to write the code myself, because it would likely be the less secure code ever written. :-D I’m not a developer.)

[strider72]

In the "get started" list ("start publishing", etc.) why not make each of those a link? Don't make the new user hunt for it -- give them direct links, and in doing so, give them a nice guided overview of the Admin interface. :) (Non-techie wife says: "That's good because they can save the post and when they want to do those things again later they can go back to the post and the links are there." From my personal experience, this sounds silly to a techie, but non-techs really do commonly think like this.)

Also, I have no problem with the "subscribe" link being a one-item list. It's a very short "to do" list. ;-) Yes, a list can contain a single item and still be a list. (Non techie wife says: "It's all one list, there's just a paragraph or two in the middle of it.")

I would make the "update notifications" a bit simpler. Yes, simpler:

"When you subscribe you will receive an email every time an update is available. This will make it easier to keep your site up-to-date, and secure from hackers and spammers. When a new version is released...."

(I was going to say axe the "go into Dashboard" instruction, but NTW says "keep it".)

[filosofo]

Looks good! Thanks for considering my suggestions. Just one more niggle, please:

"Upgrading only takes a couple of clicks!"

should be

"Upgrading takes only a couple of clicks!"

[demetris]

New Hello World! post for 2.9, revision 5, with thanks to strider72

[demetris]

New revision is up, improved and simplified thanks to strider72’s input.

See all revisions live and formatted:

• ​http://op109.net/198/wp-29-hello-world-r005-strider72-input
• ​http://op109.net/184/wp-29-hello-world-r004-filosofo-edition
• ​http://op109.net/176/wp-29-hello-world

Editable copy at:

• ​http://op111.etherpad.com/3

Changes in revision 5:

1. Changed “P.S.” back to “PS”. All sources I checked (Merriam-Webster Online, New SOED, New Fowler) have it unpuctuated.

2. Removed periods from end of action items. Authorities here say that in such cases (bulleted lists) you should use a period or a semicolon when each item is a full sentence. But I think this is wayward advice and that authorities need to catch up with the times: Punctuation is a pragmatic, utilitarian device. When the items are more than sufficiently separated by bullets which are several times the size of a period, what do we need a period for? Plus, my eye tells my that the periods in this case slow down the lively rhythm of the todo list.

3. Changed “only takes” to “takes only”.

4. Improved and simplified notifications explanation following strider72’s input.

5. Changed post_title to “Welcome!” and post_name to “welcome”.

6. Linked action items to their admin screens. (The fully qualified URLs are put together by using get_bloginfo('wpurl').) This makes the list more useful, but there is something I don’t like in the idea of printing admin URLs for every visitor regardless of capabilities.

[arena]

Why not adding a nice picture to also promote the media tools of wp.

Personnally i love this one :

​http://en.wikipedia.org/wiki/Werner_projection

[demetris]

New revision is up. See all revisions live and formatted:

• ​http://op109.net/224/wp-29-hello-world-r007
• ​http://op109.net/198/wp-29-hello-world-r005-strider72-input
• ​http://op109.net/184/wp-29-hello-world-r004-filosofo-edition
• ​http://op109.net/176/wp-29-hello-world

Editable copy at:

• ​http://op111.etherpad.com/3

Changes in revision 7:

1. Added “(and only then)” to when subscribers receive notifications. I’m not sure it’s necessary though...

2. Linked “log in to the Dashboard” (suggested by mjaquith).

3. Filled the TITLE attributes of all links.

4. Added an one-sentence paragraph that explains how to make the post private and also has an Edit Post link. (I’ve hardcoded the post ID. Is it likely that it will be anything other than 1?)

TODO

Proper i18n. I don’t how exactly to do this myself.

I tag with COMMIT nevertheless, to get this out sooner than later.

[demetris]

New Hello World! post for 2.9, revision 7

[demetris]

Replying to arena:

Why not adding a nice picture to also promote the media tools of wp.

Personnally i love this one :

​http://en.wikipedia.org/wiki/Werner_projection

I am reluctant to add anything else at this point. I think that we are already at a lenght where any more content dilutes the message. Here are all suggested action links that have been left out:

• To the bug tracker (suggested by westi)
• To the forums (suggested by many, I personally don’t like the idea)
• To the media uploader/editor

Another thing is that, already at this length, the message doesn’t look very attractive in the default theme. (Although it looks fine with the Thematic theme in op109.net.) And we also have to think of the translators, who will not be very happy with all this new text.

A last thing: ​http://weblogtoolscollection.com/archives/2009/11/05/wordpress-2-9-revamps-hello-world/ has some comments, generally positive, on the new content. A couple of people say that this content will have to be modified for WPMU. (I am not familiar with MU myself.)

[automattor]

(In [12212]) First pass first post improvements. See #11008 props demetris.

[demetris]

Thanks for fixing the i18n bits, westi! Now I know how to do it properly. :-)

[Viper007Bond]

The default post shouldn't have paragraph tags in it. Let wpautop() do it. Write it as if you were writing a normal post in the HTML editor.

[westi]

Replying to Viper007Bond:

The default post shouldn't have paragraph tags in it. Let wpautop() do it. Write it as if you were writing a normal post in the HTML editor.

Good point!

[demetris]

OK. I’ll change that.

Another thing: Is there anything we can do to make the text more friendly to translators? Say, break in into multiple strings? Maybe ask Nikolay to have a look?

[westi]

It is already done! - [12252]

[demetris]

New Hello World! post for 2.9, revision 7 with an alternative format for the string

[demetris]

Peter, your commit needed a few more line feeds. Which also points to an issue with Viper007Bond’s suggestion: If we are to rely on wpautop, we will have to use double line feeds for the paragraphs. I think I prefer straight HTML to that.

In any case, I attached for consideration a revision with an alternative format. It does two things:

1. Takes much HTML out of the translatable text
2. Splits the string into muliple strings, for easier maintenance

Would something like that be better for translators?

[dd32]

Splits the string into muliple strings, for easier maintenance

IMO, That just makes it look ugly.. and unmaintainable.

For translation, Just translating the entire block of text would be best i think, That allows for localized packages to not only translate the post, but to insert locale-specific paragraphs.

I'd nearly suggest leaving the HTML in there.. just looks cleaner.. but, as said, thats what wpautop is for, so might as well put the double \n's in.

[demetris]

@dd32:

Translators can still do that. For example, you just insert a:

<p>Blah blah blah.</p>

at the start or end of a string, and you are done. (I do it all the time.)

About maintenance, I was thinking cases like this: Say that, after feedback from users, we decide to drop one of the paragraphs of one of the list items for 2.9.1 or for 3.0. Translators will not have to do anything at all with the alternative format.

Or, another possibility: Strings are made re-usable when they are short and self-sufficient. (That’s something that I think is worth investigating in a wider context, and that could possibly facilitate the localization of plugins and themes.)

The only downside I see with the splitting is that some strings may need annotations to make sense. (Not at the moment, because they are all in a row in the POT file.)

[Viper007Bond]

There's nothing wrong with double line breaks. Infact that's how one normally writes (say in a word processor). Not to mention the paragraph tags show up when you edit the post in the current version (that's how I noticed it).

[westi]

We shouldn't split in into multiple strings as that will make it harder to translate and enforces too much layout onto the translators.

I think it is better to put in the double line breaks.

We can't do this by adding \r\n into the string as we ant to keep it a single quoted string as otherwise you have to escape the replacements for printf which makes it harder to translate.

I think the best solution is to include some double line breaks in the string.

I have made some changes and confirmed that it is identical to the original pre-peed string.

[westi]

[12255] should make this html identical to what we had originally.

Made this text the first test case for wpautop in WordPress tests as well.

[demetris]

I attached two screenshots which I think explain why I am not comfortable with the single-string format:

Translating the single-string Welcome post:

​http://core.trac.wordpress.org/attachment/ticket/11008/wp-29-welcome-string.png

Translating the multiple-string Welcome post:

​http://core.trac.wordpress.org/attachment/ticket/11008/wp-29-welcome-string-multi.png

The message in the first is a mess. That’s why I proposed an alternative for consideration. I am not sure I like the alternative much better, and, in any case, I am only one among the translators, so I only have one vote. :-)

Replying to Viper007Bond:

There's nothing wrong with double line breaks. Infact that's how one normally writes (say in a word processor). Not to mention the paragraph tags show up when you edit the post in the current version (that's how I noticed it).

That’s how one normally writes in a TEXT EDITOR. In word processors (like MS Office, OOo, Google Docs, TinyMCE, etc.) we just hit Enter once. :-)

Also, the paragraphs tags do not show in the editor: In an new installation, WordPress defaults to the visual editor, which removes the paragraph tags. If you switch to the HTML tab, they are not there.

[westi]

(In [12258]) Make sure the translated urls are attribute safe using esc_attr(). See #11008.

[Viper007Bond]

Replying to demetris:

Also, the paragraphs tags do not show in the editor: In an new installation, WordPress defaults to the visual editor, which removes the paragraph tags. If you switch to the HTML tab, they are not there.

Make the HTML editor your default, either by disabling TinyMCE in your profile or by switching to HTML view. Then edit the post (again). You'll see the paragraph tags (you wouldn't on a normally written post).

[janeforshort]

In the course of WordCamp NYC discussions, I had an about face on my position on this one. Specifically, I was in favor of changing the default post to have the helpful stuff, but now I am not. Why? Because to us, it makes sense, but to newbies, it creates more confusion around where the admin/their public blog/documentation begins/ends. I think the default post should remain a "sample post" for the time being until we can do some testing. The people at the newbie track at WordCamp NYC would NOT have done well in terms of grasping that this was a sample post. I think a better alternative would be to drop the helpy text into the Help tab for the dashboard on the first load and have it open by default with a dismiss or something. I just want to avoid creating confusion between blog content and help content.

[demetris]

@janeforshort:

That’s a good point — that the new first post blurs the distinction between content and administration. It is also a valid point from a theoretical point of view, but, in practice, I don’t think the new sample post will confuse any actual people.

But, most important, we have to keep in mind the practical issue from which this rewriting started, that we have some significant information (how to stay up-to-date) that we want to convey to WP users.

Putting this information in the sample post was the method people liked the most in the recent discussion. Actually, everyone seemed to prefer it to all alternatives.

Having this information in the dashboard too is a good idea, but not as an exclusive alternative. Also, the way you suggest has a serious disadvantage: If we think this information is important, offering a way so that people can dismiss it quickly is a deed that undermines our word. (That’s why in the Welcome draft I do not talk at all about deleting. I avoided that word on purpose.)

All that said, I think that the current version of the new first post has grown too long, which could dilute the most important of the message. I want to give it another try to see if I can shorten it but without making it too dense. Provided that we decide to keep it in one form or another.

[dimadin]

Here was some talk about localization but no one mentioned one problem with release notification. We link now to wordpress.org/download and not to locale site because we don't have mailing list on locale sites.

Is it possible to make mailing list for locale sites so that users could receive e-mail on their language when new locale version is available?

Further, there are some other i18n issues about default stuff. For example, slugs for default categories (Uncategorized and Blogroll) start with upper case and that can be confusing to translators (it was for me), so users of non-Latin languages could use their script for this and not Latin as they would probably do if they knew what that is. Maybe there should be also better description for this too.

Another thing that could be localized are default links. Except Ideas, Plugins and Themes, all other things now can exist for locale language, so users could go to that pages and not to English one. This way we can also promote locale sites.

Last thing is link in default comment. It points to wp.org, and it should be i18n so that it points to locale sites.

Any thought on this?

[janeforshort]

I'm thinking maybe we should wait until 3.0 and discuss it more, including taking i18n into account. I think it would be worth doing a little user research and trying a few prototyped approaches to see which solves the problem best. I know the answer in the patch is what won the dev discussion (me included), but we didn't consider the content vs documentation question then.

[markjaquith]

How do we feel about reverting this for 2.9? I agree that the "is it the documentation or is it a sample post?" issue could be confusing to newbies. Westi — what're your thoughts?

[demetris]

Here is an impromptu suggestion from me:

Leave it in for 2.9 and remove it in a point release if there are reports of confusion.

This sounds flippant to me even as I write it: it may seem we are using end users as guinea pigs — yet, upon consideration, it is not that bad. The new default post is not something that went in thoughtlessly, and, also, having it in a final release may be the best way to get good feedback — maybe not so much from end users (I suppose most would not go into the trouble of signing up in wp.org just to report something like this) but from people who interact with end users.

[westi]

We discussed this at length in this weeks dev chat (​http://wp.me/pbNCB-7l) and the conclusion was to revert this change for 2.9 and revisit the idea of improved admin experience after the install is complete with helpful hints etc.

I am going to revert the changes and close this ticket - we will work on the other stuff under a new ticket.

[westi]

(In [12366]) Revert [11212], [12252], [12255] and [12258]. Stick with Hello World for now and we will look at other solutions. See #110808.

[westi]

Closing this as wontfix but leaving the milestone as some commits went on for it.

[dd32]

See #11651 for an updated proposal.