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.
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.
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.
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
@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. We’ll just have to wait a bit for readme parsing to be thing.
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. 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.
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.
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.
We’ll just have to wait a bit for readme parsing to be thing.