Plugin Directory: Installation instructions missing - May withhold essential information

[Gahapati]

The Plugin Directory's previous tab for installation instructions went missing in the new Plugin Directory. -- This might not seem a terrible loss in those numerous cases, where the only installation instruction given is yet another description of how to install a WordPress plugin as such. There must be tens of thousands of such cases.

In many cases, however, plugin developers have chosen to use the now gone Installation tab to give not only meaningful but essential instructions regarding plugin deployment and usage. I've seen many cases like that.

In these cases the now missing/inaccessible installation instructions mean that a given plugin can no longer be installed and made to work correctly, and it may even appear broken because of this!

[Otto42]

I've seen many cases like that.

Can you provide examples where this is a critical issue?

Because, it seems to me, that in almost all cases, this information could be moved to the description, or the FAQ, or better yet just put into the plugin itself so that it does the correct thing on installation.

[Ipstenu]

I'm moving this to future since the majority of plugins have standard installs and any changes aren't mission critical though they may be desired greatly.

[samuelsidler]

In those cases where plugins want installation instructions, I'd recommend they add them to their FAQ and/or as a page seen after installing the plugin itself. I'd be in favor of closing this ticket, pending further feedback.

[GamerZ]

+1 to this. I use the installation instructions to ask user to add in PHP code to the theme. Adding it as a FAQ works, but is weird.

[Ipstenu]

Considering we no longer accept plugins that require you to edit a theme for it to work, that's really an old edge case @GamerZ :/

[lukecavanagh]

Granted most install guides for plugins are the normal download plugin and install using zip download by uploading it, but some do include the steps after upload and activation though.

[samuelsidler]

Replying to lukecavanagh:

Granted most install guides for plugins are the normal download plugin and install using zip download by uploading it, but some do include the steps after upload and activation though.

We are all aware of the why this ticket was filed, as mentioned in comment:0. There is no reason to leave comments repeating the description.

[lukecavanagh]

I was leaving my voice on this meta ticket, in the form of a comment.

Replying to samuelsidler:

Replying to lukecavanagh:

Granted most install guides for plugins are the normal download plugin and install using zip download by uploading it, but some do include the steps after upload and activation though.

We are all aware of the why this ticket was filed, as mentioned in comment:0. There is no reason to leave comments repeating the description.

[Ipstenu]

Replying to lukecavanagh:

I was leaving my voice on this meta ticket, in the form of a comment.

That's literally what the watch stars are for. When you're interested and invested in a ticket, but currently don't have anything constructive to add to the conversation, you follow the ticket. We use them to gauge interest and keep the signal/noise ratio low.

[lukecavanagh]

@Ipstenu

Seems like it is still defined in the class template

https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/class-template.php#L150

[Ipstenu]

... Yes? And the point?

We're not currently displaying it because in the majority of cases it was not useful. That hasn't changed.

In many cases, however, plugin developers have chosen to use the now gone Installation tab to give not only meaningful but essential instructions regarding plugin deployment and usage. I've seen many cases like that.

We'd still like some examples like that.

[GamerZ]

@Ipstenu for my plugins, I normally let the user have the option to insert the PHP code in the theme if there are technical. Or they can choose to use shortcode. The shortcode instructions are also displayed under installation.

For example WP-PageNavi ​https://github.com/lesterchan/wp-pagenavi, you have to replace your theme existing navigation. There isn't really a automated way of doing it. So I put it under Installation instructions. It makes more sense than a FAQ like "How do I use this plugin?"

[Ipstenu]

Right, you're the exception here :)

I'm not saying you're wrong and there isn't SOME merit to that section, but it's a lot less when you look at 65,000 plugins.

So I put it under Installation instructions. It makes more sense than a FAQ like "How do I use this plugin?"

That's somewhat subjective as there are a lot of ways to explain that one, in a FAQ or even in the basic description.

[GamerZ]

Yea, for now I will put it in the FAQ or description till there is a decision made on this =D I started having support questions on how to use the plugin ever since the installation instructions are gone!

[anonymized_11892634]

Some of my plugins have been hit by this issue too. However, I don't have any issues adding a "How do I install this plugin?" section to the FAQ. Personally, I think removing the dedicated install section works well to slim things down so wouldn't necessarily want to see it reinstated.

I think it should become less of an issue when people become more used to the new layout and where to look for information.

[mrpritchett]

Replying to Otto42:

I've seen many cases like that.

Can you provide examples where this is a critical issue?

Because, it seems to me, that in almost all cases, this information could be moved to the description, or the FAQ, or better yet just put into the plugin itself so that it does the correct thing on installation.

Otto,
This is a critical issue because of users. If we're going to follow with the idea that users are the target, we just removed the ability for 80% of our install base to install any plugin that requires a shortcode or template tag or any sort of "insert." While that info can be moved, we made a change without informing any plugin authors that this would be a requirement. So we're going to make the plugin repo unusable until plugin authors can catch up if they realize something is wrong? That seems to hurt the vast majority of "users" who aren't developers. I AM a developer and ran into this issue 4 times this morning already. While I can overcome it very easily, your average user cannot. I'd be happy to help code a solution, but am hesitant if there is a lack of understanding how high a priority this is for users.

[javorszky]

Another issue is for the users who are new to WordPress. They likely haven't seen WordPress admin before, but were told / suggested to use WordPress, and <this plugin>, and they were given a link to the plugin on the repository. Currently the only action they can take there is Download it, but there's no other information about what to actually DO with the plugin. Even a link to a doc page about "what are plugins and how to get them installed on your WordPress site" (essentially the copy of the "upload to the plugins directory" text) would be nice. It's not there.

And then there are the suites of plugins that not only require users to have them installed, but also to have accounts on other services, otherwise the plugin is dead code. Plugins such as:

• sendgrid
• mailchimp
• mailgun
• s3 offload
• google analytics

...

The above are examples for

In many cases, however, plugin developers have chosen to use the now gone Installation tab to give not only meaningful but essential instructions regarding plugin deployment and usage. I've seen many cases like that.

[jb510]

I've always found the "install" tab nearly useless, except where a plugin author has gone the extra step and explained "getting started".

So, while I understand getting rid of this based on the majority of cases where the install instructions an author included are a copy pasted version of "1. install plugin, 2. activate plugin", it would be extremely helpful to have a dedicated "Getting Started" tab/section.

This is fundamentally different information from the description, and putting it in the description of which most people only read the first sentence hides what is very important information...

As an example of what I mean, have any of you bought a consumer electronics device in the last 10 years? Did it come with a manual, a manual and a quick start guide, or just a quick start guide. My guess is never the first, sometimes the second and most often just the "quick start guide".

Plugins need the same thing, they need a dedicated section for "this is where you find the settings in the admin", "this is how you insert a shortcode", "this is how you get in insert your API key from X"...

[iandunn]

I think the criticism here is legitimate. This breaks back-compat, adds an unnecessary maintenance burden to thousands of developers, and was done without any significant notice.

Here's an example of a user confused because they now have no instructions:

​https://wordpress.org/support/topic/i-cant-find-shortcode/

I took a quick look at my plugins, and at least 3 out of 16 will need changes. That's almost 20%. If that ratio is representative, then I think this is a pretty big problem.

Those 3 examples:

• ​Basic Google Maps Placemarks
• ​CampTix
• ​Tagregator

They're a mixture of shortcode slugs/params, and settings.

Even in the other plugins, it's often helpful to have something that explicitly says, You don't need to do anything else, just install it and it'll start working. For example,

​https://wordpress.org/support/topic/clear-as-mud-1/

I think a much better way to handle this would be to:

1. Continue showing the Installation page if it exists in readme.txt
2. If the section doesn't exist in readme.txt, then don't show the page
3. Add a note to the sample readme.txt that says it's an optional section
4. Do anything else you'd like to encourage authors to remove the section when they don't need it. For example, write a post on make/Plugins, add a note to the Make sure your plugins are ready for WordPress 4.8 email, etc.

[SergeyBiryukov]

Replying to iandunn:

I think a much better way to handle this would be to:

1. Continue showing the Installation page if it exists in readme.txt
2. If the section doesn't exist in readme.txt, then don't show the page
3. Add a note to the sample readme.txt that says it's an optional section
4. Do anything else you'd like to encourage authors to remove the section when they don't need it. For example, write a post on make/Plugins, add a note to the Make sure your plugins are ready for WordPress 4.8 email, etc.

Makes sense to me. Maybe we could also hide the section if it exists, but has no differences from what used to be the default content, apart from the plugin slug.

[anonymized_11892634]

Over the past few days I've noticed more and more plugins that have been hit by this. I think the big issue here, as people have mentioned, is that there didn't seem to be much of a warning that this would happen. It seems like a lot of developers don't even know the install section has been removed.

I think removing the install tab is a good move, but some extra information/advice for developers seems to be needed. I've added a "How do I install this plugin" section to the FAQ of my plugins, but I'm lucky enough to have no life so can keep up with this sort of thing :p

I also totally agree with @javorszky. If a user is not familiar with WordPress yet, they will have no idea how to install a plugin. They will click the "Download" button and have a zip that they don't know what to do with (most people I work with don't even know what a zip is). Even if there was some kind of generic splash page before downloading, that would be a vast improvement for the average user.

[joelhardi]

This effectively breaks one of my plugins (which requires mysqli) for users who can't find the installation instructions in the readme -- the result is going to be pointless forum posts and inaccurate reviews, which in fact have already started.

All previous explanations I've left that refer users to the installation requirements at "wordpress.org/plugins/[plugin-name]/installation/" are now effectively broken links.

This seems to be a policy change to not show plugin instructions? But I say "seems" because:

1. WordPress core actually still shows an installation tab in the plugin admin section
2. ​The most current sample readme.txt linked from WordPress.org still has an Installation section so it's unclear what if anything plugin authors are supposed to do
3. The new WordPress readme validator doesn't even work, it just POSTs back to itself and does nothing

If this is a policy change that plugins are no longer supposed to contain or allow instructions then it should have been communicated and implemented in a coordinated way, right now this is just a bug.

[samuelsidler]

I can see why some plugin authors would want installation instructions, but they're definitely in the minority. For now, to get this information back in front of users, I think we should display installation instructions – if they differ from the default – at the top of the FAQ. We can call the entry "Installation Instructions."

To get the conversation started about future iterations, maybe we can display a modal after download, that says "Thank you for downloading [plugin name]. To install, upload to your WordPress dashboard. <a>See more detailed installation instructions.</a>" with the latter being a link to either a basic help doc about how to install plugins in WordPress, or the detailed FAQ section, if it exists for that plugin. This is similar to what other software down, when downloading.

Is there someone who'd like to take point on thinking through the UX interactions here and what would be the best experience for users? Perhaps we can have a scheduled chat in Slack about this topic and work with the design team to come up with a great experience.

[dd32]

In 5253:

Plugin Directory: Prefix Installation Instructions as a FAQ entry when they exist in the readme.

See #2645

[dd32]

Replying to dd32:

In 5253:

Plugin Directory: Prefix Installation Instructions as a FAQ entry when they exist in the readme.

See #2645

That will trickle in, as it requires a plugin to have a readme import triggered.

A rescan can be triggered by a plugin commit (even just a whitespace change to trunk), if this change is good, we'll re-import all plugins.

[iandunn]

I triggered an import for ​basic-google-maps-placemarks, and it looks good to me. Thanks Dion :)

Sam's thoughts in comment:23 sound good to me as well :)

[mrpritchett]

Looked at the example above. I agree that this is an acceptable solution if automatically triggered across all plugins by the team. Is that what will be happening?

[samuelsidler]

Replying to mrpritchett:

Looked at the example above. I agree that this is an acceptable solution if automatically triggered across all plugins by the team. Is that what will be happening?

Once we're happy with the direction, we can trigger an import across all plugins. We're holding off on that right now because there are other (unrelated) changes in the directory that may need an import and we'd rather do the import once since it takes a while. In the mean time, plugin authors can opt-in by making a whitespace change to their readme, as Dion mentioned.

[jb510]

Replying to iandunn:

I triggered an import for ​basic-google-maps-placemarks, and it looks good to me. Thanks Dion :)

Sam's thoughts in comment:23 sound good to me as well :)

I don't get it. I've looked at that plugin 5 times and can't find the installation instructions? ​https://wordpress.org/plugins/basic-google-maps-placemarks/installation doesn't seem to work either. Did this test get reverted?

[mrpritchett]

Replying to jb510:

Replying to iandunn:

I triggered an import for ​basic-google-maps-placemarks, and it looks good to me. Thanks Dion :)

Sam's thoughts in comment:23 sound good to me as well :)

I don't get it. I've looked at that plugin 5 times and can't find the installation instructions? ​https://wordpress.org/plugins/basic-google-maps-placemarks/installation doesn't seem to work either. Did this test get reverted?

It's in the toggle section under the Screenshots. Confirmed there for that plugin

[SergeyBiryukov]

Replying to jb510:

Replying to iandunn:

I triggered an import for ​basic-google-maps-placemarks, and it looks good to me. Thanks Dion :)

I don't get it. I've looked at that plugin 5 times and can't find the installation instructions?

[5253] adds installation instructions as the first entry in the FAQ section, not as a separate section.

[jb510]

Oh! Found it. I'm on an iPad at the moment and scrolled past it every time, text string search failed me too but I'm not sure why. That said I still find it hard to find anything I'm looking for with the new one page layout.

Just voicing a concern here, when those install instructions are most important they are usually long and complex, burying them in an FAQ doesn't seem a great solution in those cases. Why. It keep them their own section?

The faq solution also doesn't address the broken link problem @joelhardi mentioned above, is there going to be a redirect to the FAQ?

[anmari]

Some of my plugins were affected by this, where they essentially lost all the detail steps - too detailed for the description, and not really FAQ.

Please could we at least have some warning if there are to be more such changes.

Please also consider consistency.
If the readme example has an Installation step at a high level, then the installation should be at that level in the plugin directory.
If it's to be a step in the FAQ, then that is how it should be shown in the readme example.

Right now I'm not sure what to do. It seems easiest is just to force an update on my plugins to trigger this 'first step' in FAQ idea. But longer term ?

[ocean90]

[5397]