Add new plugin/theme readme header tag for documentation link

[danieliser]

As simple as that sounds I think it would go a long way.

Could be used to display link to docs via

• wordpress.org plugin page
• plugin installer
• All Plugins page next to deactivate

This way users can definitely not miss documentation entirely as currently happens frequently no matter how much we try to get them there.

[SergeyBiryukov]

Wouldn't it be enough to put the link to the docs to plugin's Description, Installation, and FAQ tabs? If some uses still manage to miss it, I don't think having one more link would help much.

[danieliser]

I don’t disagree that it should be enough, but in my experience it isn’t.

My plugin Popup maker does in fact link to docs from description and faq tabs. Will have to check installation. That said we even have inline documentation links for many settings as well.

Still get users nearly every week saying there was no documentation which is bananas. We have probably 100+ pages of docs.

If it was a standard feature in the readme and gained adoption, and of course was displayed where only plugin meta can be.

Further places it could be placed:

• A checkbox on the support ticket form agreeing they have searched the docs with a link to them (if they exist)
• Links in the sidebar of the support forums for each plugin could include links to docs
• Enhanced plugin search could promote those with docs
• Searh results could potentially list that the plugin at least has documentation with an icon for instance.

Most of those would be unavoidable for the user, especially if they were trying to get help.

That said none of them can be accomplished if there is no standardized way of feeding that data.

[Otto42]

Could be used to display link to docs via

• plugin installer
• All Plugins page next to deactivate

Core doesn't read the readme.txt file at all. Anything there would not show up in WordPress. To put links in the installer and/or plugins page is a core change, not a meta change.

[danieliser]

@Otto42 Great point, scratch the All Plugins page from my list

The plugin installer info is rendered via api data pulled from meta, so that one is in fact in the right place as this needs to happen before core can consider making changes to display it.

[obenland]

Isn't this covered with Plugin URI? I'm not sure I understand how documentation shouldn't be part of that.

Adding readme headers are not trivial, impacts thousands of plugin developers, and increase the Plugin Directory's complexity. I'd rather we not do that.

[danieliser]

@obenland So if we have docs we have to choose between that link and one to our sales/general info site, if so I'm gonna choose to send users where they can learn about the product as a whole (features, upgrades, blog etc) as any other plugin developer who monetizes would.

I mean you can decide this isn't worth working on, but I think documentation is a hugely important part of the WP ecosystem, enough to warrant its own spot/url when available & relevant. We have entire teams dedicated to docs for core and the other WP systems already which proves that it matches the communities direction and has potential to reduce support loads in general.

Most plugins of substance (those that actually require substantial docs) are more and more moving documentation to its own portal such as HelpScout.

Just took a quick look for reference at the current guidelines for plugin readme & headers, this is the only definition of what plugin uri should be.

Author and Plugin Homepages
The Author URI and Plugin URI fields of the plugin header. The Plugin URI should be unique to
each plugin.

• ​https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/

And again

Plugin URI: The home page of the plugin, which should be a unique URL, preferably on your own
website. This must be unique to your plugin. You cannot use a WordPress.org URL here.

• ​https://developer.wordpress.org/plugins/the-basics/header-requirements/

Clearly they don't intend you to put doc link there.

[obenland]

Please let me know if I'm missing something, but why can documentation not be part of the plugin homepage?

​Akismet for example does exactly that, or ​All In One SEO, or ​Wordfence

[danieliser]

None of them have docs on the home page, they all link off to docs, same thing we do, it simply isn't effective enough.

Secondly because our docs are self contained along with our internal ticketing systems and not part our our sites directly. Sure I could build an api to duplicate what HelpScout offers via my own WP site, but then I would spend all my time doing that and not moving my products forward.

Again, just a suggestion based on years of personal experience as a developer that supports plugins on the repo. Pretty sure I wouldn't be alone in this thinking. Guess we will see.

[danieliser]

I will also add that a great deal of our support tickets come from users who never, repeat never, actually visited our site via the plugin uri url, so again how effective is it?

Now if in order to submit a ticket on wordpress.org plugin forums they had to check that they had checked documentation to submit a ticket it would force users to at least consider the answer might already exist. Not that they couldn't click the box anyways.

Again your gonna say add a sticky post letting users know and let them know in the readme and faq tabs etc. Done, done, done. Doesn't prevent them all, neither will this, but every part helps.

[obenland]

Replying to danieliser:

I will also add that a great deal of our support tickets come from users who never, repeat never, actually visited our site via the plugin uri url, so again how effective is it?

What would make a documentation link more effective than the plugin url?

[tellyworth]

@danieliser we need a strong argument in order to add new header or readme field. Can you give a clear proposal that shows exactly what you're suggesting, perhaps with mockups showing what it would look like, and an explanation of what it achieves that can't be solved by other means?

[coffee2code]

We can all agree that documentation is imporant and that it'd be great if users read them. However, the proposal doesn't provide sufficient justification that any of the suggestions do much more than what is already available. And there hasn't been any traction on this in 2+ years. As such, closing as wontfix.