Add a link to docs page

Expected behavior

I should be able to access the docs for a plugin quickly and easily.

Current behavior

At the moment to find docs for a plugin requires a long journey. For example, to get here:


took about 8 clicks and a lot of searching around.

There is no way to get to Classic Commerce docs at all.

Possible solution

Include a direct link to plugin docs.

Context

If I am assessing a plugin I will always look at the docs. I generally assess the quality of a plugin by the quality of the docs. I can’t recognise good code but I do know good writing. If the developer has spent a lot of time on the docs and they are accurate and well-written then I can assume that his code has a similar approach.

3 Likes

Agreed, this should be something plugin devs can add/update :+1:

The easiest way to do this will be to encourage plugin developers to add a link to their docs in the GitHub readme, and the directory will pick it up from there.

1 Like

I think this is a flawed premise. Most developers don’t like to write docs. Or they speak a different language and it reflects in the docs. Or they spent too much time on the docs that they skimped on the code (or testing). Or they had someone else write the docs…
It just doesn’t hold up.
But having a link to docs is a good goal.

2 Likes

Maybe, but it’s the only one I’ve got.

I also don’t buy things from online shops that have lots of spelling mistakes. Probably miss out on a lot of bargains. :slightly_smiling_face:

2 Likes

I think encouraging good docs is enough of a reason to make it a field devs can update and making it obvious about what plugins actually have docs.

In the short-term, ya having it in the readme is the easiest way to implement it once we start parsing that, still leaving this feature request open so we can keep it mind though :slight_smile:

An in-between approach would be to recognize certain structures in the readme as “fields”. For example:

# My Plugin

some text

## Documentation

https://docs.myplugin.com/

## Support

https://support.myplugin.com/

The directory could parse this and link to docs.myplugin.com for documentation and support.myplugin.com for support.

2 Likes

That would be a neat solution. Then a plugin dev could keep all the fields up to date just by changing the readme.

1 Like

@ozfiddler, I thought the same thing…how will they find the docs? Then, I said, “Meh, who is going to read the docs.” I suppose at least they do exist, even if they’re not easy to locate via the directory. :wink: We’ll just have to wait a bit for readme parsing to be thing.

1 Like

But the way it is at the moment I don’t even know if they exist at all. I may go searching for nothing.

I feel your pain! While I can’t speak for everyone, I personally don’t release any plugins without documentation. So, if it’s a Code Potent plugin, you can be sure there are docs attached to the plugin in my onsite directory. :slight_smile: In fact, I have several as-yet-unreleased plugins that could be used in production today… just, the docs are incomplete…and, thus, so are the plugins.

2 Likes

I forgot that “fields” functionality already exists in plugins! See: https://developer.wordpress.org/plugins/plugin-basics/header-requirements/#header-fields

Given that, probably not the best idea to invent another standard for parsing fields!

4 Likes

James, the only caveat I can see is that “fields” aren’t typically added to a README.md, they’re usually added to a readme.txt. While the format is identical, if we add the fields to the README.md, they will render onscreen at GitHub. I’m also not confident that the README.md is suited for our purposes as it often contains a lot of technical developer information that the directory shouldn’t necessarily display. Personally, I don’t add much content on GitHub (ie, header fields, info, docs)… I just have a short description and links to the docs (which I prefer to host on my own site as the single source of truth.)

Maybe we could come up with a middle-ground solution. Something like… by checking if there is, say, a directory.md file in the plugin’s repo…and pulling that content for the directory as a first course. If that file doesn’t exist, then try for a readme.txt… and only use README.md as a last resort. The format would be identical, just, we wouldn’t have to alter what is displaying on our GitHub pages in an attempt to make the texts appropriate for dual audiences.

Header comment, as rendered on GitHub.

The plugin header (and the fields) go in the plugin’s main PHP file, not the readme.

That mechanism is going to have to stay mostly as-is, and the directory is going to need to parse that data anyway for various purposes, so we might as well use it for things like “Support URL” and “Documentation URL”.

As far as the readme itself, which is like a long-form description that can contain markup and links, I agree, readme.txt should be the primary source for this content, and then README.md if that doesn’t exist. I don’t see a need to introduce a third file for that purpose (or a fourth file if you count the plugin’s main PHP file).

For plugins I write that are hosted on GitHub and not released on the WP.org directory, I usually just write about it in README.md. For existing WP plugins, and for people who are using the WP convention of readme.txt, we should try to have this mostly just work as-is in our directory too.

3 Likes