Move Optimization Detective docs into README.md

[westonruter]

After the most recent release of Optimization Detective, I discovered that the plugin directory has a 2,500 word limit for readme.txt files. And Optimization Detective now exceeds the limit:

This is resulting in the readme being truncated:

So this PR moves the Background, Technical Foundation, Use Cases/Examples, and Hooks into a README.md which is then linked to from the readme.txt. The initial two paragraphs of the plugin description are retained in both places for context. Sections are also added for installation, feedback, support, contributing, and security. There is also a new section added for extension plugins.

This also further improves the OD-related plugin readmes with a notice that the REST API must be available to unauthenticated visitors. See #1731.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: westonruter <[email protected]>
Co-authored-by: swissspidy <[email protected]>
Co-authored-by: felixarntz <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[westonruter]

• The formatting of the accepted arguments to each action/filter could be added and improved.

[westonruter]

Also good to add, although not necessary immediately:

• How to write an extension
• Class reference
• Function reference
• JSON Schema
• Remove access private from anything exposed by filters or hooks
• Extract hooks docs from PHPDoc?

[felixarntz]

Maybe we should add a dedicated docs folder, or a Wiki, or something like that? The documentation needs for OD would probably justify a dedicated location like that.

[westonruter]

I thought about a Wiki too, but @joemcgill suggested a README due to it being easier to keep up to date in code (as changes can land with new features in PRs). At the same time, edits are also burdensome since they have to go through the PR process. In any case, I think a README as a landing page makes sense and then we can break out sections into separate docs pages, whether that be in a docs subdirectory or a Wiki (which we'd have to enable for the repo, but then why not use the Handbook?)

[felixarntz]

@westonruter

I thought about a Wiki too, but @joemcgill suggested a README due to it being easier to keep up to date in code (as changes can land with new features in PRs). At the same time, edits are also burdensome since they have to go through the PR process. In any case, I think a README as a landing page makes sense and then we can break out sections into separate docs pages, whether that be in a docs subdirectory or a Wiki (which we'd have to enable for the repo, but then why not use the Handbook?)

I think a docs folder works best, for the reasons you're saying, because it's part of the repo. +1 on linking to it from the README.md (and readme.txt). The constraints of using README.md make it difficult to overview as all the documentation is by definition on one long page. And with readme.txt also containing (some of) the documentation, there's a lot of duplication. So moving it all to a docs folder and linking to it improves the situation in various aspects.

[westonruter]

@felixarntz How about this now? The docs are split into three files, with the README serving as the index and location for introductory information and small sections, with then separate docs containing docs for extensions and hooks:

1. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/README.md
2. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/docs/extensions.md
3. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/docs/hooks.md

[felixarntz]

I don't it's necessary to have this file act as a second version of a readme (next to readme.txt). There is still some duplication here, and I don't see why that's useful.

I think it would be better to trim this down to purely the documentation bits (e.g. change the title to something like "Plugin overview" or "Plugin introduction") and then move the file to e.g. docs/introduction.md.

On a related note, it might be helpful to create a docs/README.md file that acts as a table of contents for the available documentation files. You could then also add a "Back" link to each individual article file in docs, to simplify navigation.

[westonruter]

OK, now with 52254ce there is:

1. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/docs/README.md
2. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/docs/introduction.md
3. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/docs/extensions.md
4. https://github.com/WordPress/performance/blob/update/od-readme/plugins/optimization-detective/docs/hooks.md

[felixarntz]

Thanks for the updates @westonruter!