[wp-meta] [Making WordPress.org] #2645: Plugin Directory: Installation instructions missing - May withhold essential information

[Making WordPress.org]

#2645: Plugin Directory: Installation instructions missing - May withhold
essential information
------------------------------+-------------------------------------------
 Reporter:  Gahapati          |       Owner:
     Type:  enhancement       |      Status:  new
 Priority:  high              |   Milestone:  Plugin Directory v3 - Future
Component:  Plugin Directory  |  Resolution:
 Keywords:                    |
------------------------------+-------------------------------------------

Comment (by 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:
 * [https://plugins.trac.wordpress.org/browser/basic-google-maps-
 placemarks/tags/1.10.7/readme.txt Basic Google Maps Placemarks]
 * [https://plugins.trac.wordpress.org/browser/camptix/tags/1.5/readme.txt
 CampTix]
 *
 [https://plugins.trac.wordpress.org/browser/tagregator/tags/0.6/readme.txt
 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`
 1. If the section doesn't exist in `readme.txt`, then don't show the page
 1. Add a note to the sample `readme.txt` that says it's an optional
 section
 1. 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.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/2645#comment:19>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org