How about some documentation?

So, query the forum for “remove footer” and see which dates come out on top: the oldest ones.

That’s the forum search – not the forums themselves. The search is currently provided by Google and we cannot control the ordering of the returned results.

As for evaluating tools that are submitted, do you mean you actually don’t try them out? How else can you evaluate something?

Submitted themes & plugins are evaluated against the appropriate submission guidelines. If that is something you are interested in, please see them Theme_Review and Plugin submission guidelines. Further evaluation would require using the plugins in multiple real life scenarios over a very extended period of time. As both a theme & plugin developer, I know all too well just how difficult this is and it simply is not realistic to do this on www.ads-software.com.

I sense you are getting defensive because I’m criticizing WordPress.

No. I am simply trying to explain the real situation to you. WordPress, its themes & plugins are developed by a large community of unpaid volunteers. What you seem to be asking for is beyond what could reasonably be asked of these volunteers. It therefore makes sense to discuss any shortcoming in plugin or theme documentation with the plugin or theme developers themselves rather than insisting that the wider community “do something” about it.

So the result of all this discussion is nothing gets done.

What I’m asking for (and volunteering to help with) is better organization and better evaluation of plug-ins and themes. This seems like a very reasonable request but you say it can’t be done. You can’t test drive new plug-ins to see if they work, you can’t ask volunteers to evaluate the documentation submitted with new plugins and you can’t write your own search queries.

I’m sure you’re a hard-working volunteer but that “can’t do” attitude is no help to your organization.

…that “can’t do” attitude is no help to your organization.

The WordPress community is far more of an ad-hoc society than any kind of organization, and it certainly does not have any kind of “can’t do” attitude! This same type of discussion questioning the community took place some time ago concerning the WordPress “Security Review Process”:
https://www.ads-software.com/support/topic/security-review-process?replies=32

You can’t test drive new plug-ins to see if they work

As I have explained “test driving” a plugin takes a lot more than just installing, activating and seeing it work. It can takes weeks to run proper tests.

you can’t ask volunteers to evaluate the documentation submitted with new plugins

Would you be willing to take this on (serious question)?

you can’t write your own search queries

The Google search was added as a temporary stop gap. Work is ongoing to upgrade the forums but as this is a truly mammoth task, it’s going to take time. And patience.

I see a great deal of you asking other people to do things but nothing of you offering to contribute. So what can you help with?

you can’t ask volunteers to evaluate the documentation submitted with new plugins

Would you be willing to take this on (serious question)?

Yes, I’d be glad to review documentation and cajole developers into providing better explanations where they seem to be needed. I’ve had a look at the Get Involved section but I’m not sure how to proceed.

Suggestions?

You could have a look at joining the WordPress Documentation team. Their primary function is developing documentation for WordPress core but they are also actively developing handbooks to support plugin and theme developers as well.

I’ll also ask around and see if there are any other pre-existing initiatives that might suit.

Finally, please feel free to pick an existing plugin, review its documentation and pass all of your feedback to the plugin developer.

If you’re looking for a plugin to start with, how about https://www.ads-software.com/extend/plugins/eshop/ There are around 80 pages of documentation at https://quirm.net/wiki/eshop/ – 99% of which I authored personally – but which have never really been reviewed by anyone outside of the plugin developer & myself. I would be more than happy to have someone else point out any shortcomings.

First, thank you for taking the time to comment here. As an admin for the Theme Review Team, I am sensitive to end user needs, and ensuring that Themes hosted in the WordPress Theme Directory serve those needs to the greatest extent possible.

To address some of your issues as they relate specifically to Themes:

1. The Theme Directory listings are at a bit of a disadvantage as compared to the Plugin Directory listings. With the Plugin Directory listings, Plugin developers are required to include a README file that is compliant with a specific markup standard. The Plugin listing then parses that README file, to give the various headings/tabs that you see (FAQ, screenshots, etc.) in each Plugin’s listing. The Theme Directory does not have this same README-parsing functionality, so Theme developers are limited to control over only the Theme description. Fixing this discrepancy is a (very) long-term goal/project of the small (for all practical purposes: one-man) team that maintains the www.ads-software.com site.

2. The Theme Review Guidelines require Themes to support core implementation of any integrated features/functions in a Theme. So, for example, if a Theme wants to implement a custom header image feature, or a custom background feature, or navigation menus, then the Theme must use the core implementation of those features, rather than create a redundant implementation of those features. So, for all core-implemented features, users should look first to the Codex for documentation of those features.

3. The Theme Review Guidelines do require Theme developers to provide documentation for any non-standard feature/functionality of the Theme. So, for example, if a Theme implements a “featured posts” slider, then the Theme must document how that slider works (e.g. using sticky posts, or using a “featured” category or tag, or a “featured” custom post meta key).

4. But, as mentioned above, there is no user-friendly display of a Theme’s README file. Unfortunately, there’s simply no way to parse/display them in the Theme’s directory listing page.

5. If you find Themes that don’t have non-standard features documented well enough, please post in the Theme’s specific support forum.

6. But always, please keep in mind, the vast majority of people who submit Themes to be included in the Theme directory are submitting free code that they have developed on their own time. Writing user-friendly documentation is a skill; it is hard, and it is time-consuming.

7. While I do intend to push for Themes to have Plugin readme-standard compliant README files, it would be impractical to try to define some standard of inline documentation, and would incur an incredible burden for an already very busy Theme Review Team.

Here’s my own Theme, Oenology. I consider its documentation to be a feature. I can’t tell you how many hours I’ve spent on documentation alone, and it’s still not perfect. I try to provide the same quality of documentation for my Plugins as well – but again, I don’t think it’s practical to try to require all Plugin and Theme developers to meet some level of quality of documentation.

Many Plugin/Theme developers are open to contributions to their code. The best places to start inquiries are the Plugin/Theme’s specific support forum, or, as is often provided now, the developer’s GitHub repository for the Plugin/Theme. Many developers use GitHub as a VCS, and welcome forks/pull requests. I imagine that the vast majority of developers who host their code on GitHub would practically beg for someone to help with their documentation especially.

If you have input or feedback regarding the Theme Review Guidelines, please feel free to contact the Theme Review Team directly. We always welcome any and all input, feedback, and criticism.