Main sections of the page

[schlessera]

Sections proposed in https://make.wordpress.org/core/2017/08/10/php-meeting-recap-august-7th/ :

• What we want from you
• Call to action
• What is PHP?
• Why do you need an update?
• What should you need to know before doing an update?
• How do you do an update?
• Call to action

[nerrad]

Here's some ideas on context statements for each of those:

What we want from you
Highlighting the goal of this page for the end user. We want them to get their site on a later version of PHP.

What is PHP?
Basic overview of what PHP is and how it powers WordPress (along with other stuff).

Why do you need an update?
Benefits of updating PHP.

What should you need to know before doing an update?
What preparation steps should be taken to get determine whether your site is ready for a PHP update and how to determine readiness.

How do you do an update?
The steps to update your PHP version (we could dynamically link to host specific steps maybe).

[nerrad]

I think the given outline has been agreed on and I can live with it. But personally I think having things grouped into three major headings would work a bit more better from an organizational and concise standpoint. I would volunteer:

1. What is PHP

Very BASIC overview of PHP and it's importance for running WordPress. no more than one or two small paragraphs.

2. Why PHP version matters to you as a Site Owner?

This would include the benefits of being on a later version of PHP (at least one of the supported versions of PHP).

3. How do you upgrade the PHP version on your web site?

This would include preparation and actual update steps for getting their site updated. Content could also be dynamically linked to relevant host instructions where/when possible.

[tfrommen]

Essentially, this only merges the last two sections into one, because the first thing really should be "You should be running up-to-date PHP (for good reasons)", and not "What is PHP".

I see it just as @schlessera mentioned in one of the earlier meetings: I want to know right from the start what this is about, and not when I'm done reading all the things and I now even know for myself what this is all about (and maybe even that it isn't for me).

The What part could be as concise as an introductory paragraph, not more. Then you have the three-items list of sections, wrapped in CTAs.

Like I said, we only merged two items.

[nerrad]

How can we explain the benefits of PHP to site owners who potentially don't know what PHP is to begin with? This is primarily why I suggested it as the first item. However, I do get that presenting the purpose of the page as the first thing people see being important. So instead of the first item being "What we want from you?" Maybe it could be "Why you want to read this?" and its content could be the tldr; for the entire page. That way site owners can skip the "What is PHP" part if they already know what PHP is.

So a modified section structure would have something like this added to the first section:

Why you want to read this

One of the important software components that enables WordPress to run on all sites is PHP. On this page you will learn what PHP is and why being on the latest version of PHP is so important for your site.

What is PHP?

A skip to next section link could go here.

Why PHP version matters to you as a website owner

How to upgrade PHP for your website

(sprinkled with the CTA's of course)

[felixarntz]

@nerrad I like your latest proposal. I agree with the previous comments that the beginning should contain what we want the user to do (of course phrased differently), before getting at what PHP is and its benefits. Users definitely need to be informed about PHP, but if they don't know why they should be informed, they'll quickly stop reading.

I like the idea of not having a dedicated section "What should you need to know before doing an update?" as this can easily cause unnecessary worries on the site owner's end. I think these concerns should be addressed in the upgrading PHP section, alongside helpful tools where they can evaluate (as accurately as possible) whether their site is ready, or if not, what's not ready. A section dedicated to this puts too much emphasis on it and distracts from our actual goal.

[ahmadawais]

What about a pre-written email for users to send to the hosting support team? That should make things easier.

[schlessera]

Three approaches for the introductory paragraph were identified from Slack discussion.

The "technology" approach:

One of the important software components that enables WordPress to run on all sites is PHP. On this page you will learn what PHP is, why being on the latest version of PHP is so important for your site, and some steps you can take to make sure your site has the latest PHP version in use.

The "detected issue" approach:

Your website might not be operating at its full potential. This page will tell you about an important issue we have detected and how to go about to resolve it (no jargon!). Let's talk about what PHP is, and why you might need to update it.

The "probability" approach:

You want your site operating at its full potential. Is it? As many as 4.5% of sites running WordPress are not. This page will help you determine if your site is one of them and how you can fix that.

We can either further discuss which approach to take (before then optimizing that one in detail), or we can do time-limited or permanent A/B testing to find out which approach works best.

[ahmadawais]

+1 for A/B testing. There's going to be a huge audience that gets impacted by this.

[felixarntz]

@ahmadawais Creating a pre-written email is definitely on our list. https://wordpress.org/about/requirements/ actually already has a very basic version. We can probably improve that one a bit, but I think it should remain almost as short and precise.

[ahmadawais]

@felixarntz Yup, I think we can improve it a little so that both the host and the send would know the importance and wouldn't argue about it.

[felixarntz]

Updated version from today, including copy draft:

1. Introduction
   • You want your site operating at its full potential. Is it? Almost half of the sites running WordPress are not. This page will help you determine if your site is one of them and how you can fix that.
2. What is PHP?
   • One of the important software components that enables WordPress to run on all sites is PHP. [briefly explain in a non-technical way what it is]
3. Why PHP matters to you as a site owner
   • Every WordPress website requires PHP to run. PHP has many different versions, and as it is with most things in our technology world the more recent the version, the better experience you get. WordPress makes it easy for you to get started by supporting a wide variety of PHP versions, but if you want your website experience to be better, you want to make sure you’re running the latest PHP version.
   • [educate the user about what the problems with an outdated PHP version are]
   • [highlight benefits of using a current version of PHP]
   • While it would be stellar if WordPress could solve the PHP problem itself, unfortunately it is not in charge of the PHP version, since PHP runs on the server that powers your website. Furthermore there can be incompatibilities between certain PHP versions and certain WordPress plugins or themes, which it cannot detect automatically.
4. How to upgrade PHP for your website
   • Before you proceed with the update, you should try to make sure that your website including its plugins and themes work correctly with the PHP version you want to upgrade to.
   • [provide steps to prepare an update to PHP]
   • [give instructions on updating PHP]
   • [help troubleshoot issues]

Let's work towards getting drafts for the sections marked with square brackets too.

[felixarntz]

As decided today, we'll go with the "probability" approached mentioned above first. The "detected issue" approach should be used conditionally, when linked from WP-Admin due to a PHP version issue.

The "technology" approach will not be used for now, but could be part of a more-whitepaper-type of document on PHP, similar to the current .org page on security.