search

michaeluno / admin-page-framework

Facilitates WordPress plugin and theme development.
http://admin-page-framework.michaeluno.jp/
Other
340 stars 71 forks source link

Documentation improvements. #291

Open OllieJones opened 3 years ago

OllieJones commented 3 years ago

Here's an offer to collaborate on documentation.

My personal pain points?

  1. the search function isn't what it could be.
  2. the organization is a little hard for a newcomer to sort out.
  3. there's a blue stripe ... looks like a panel separator ... right in the middle of doc pages.

Still, I'll work on anything needing it.

michaeluno commented 3 years ago

Hi, thanks for your offer.

the search function isn't what it could be.

The documentation has been generated with ApiGen 2.8.0 with a custom template and the search functionality totally depends on the ability that ApiGen provides.

the organization is a little hard for a newcomer to sort out.

I'm not following what you mean.

there's a blue stripe ... looks like a panel separator ... right in the middle of doc pages.

Can you post a screenshot? Maybe it is a problem of the documentation generator.

By the way, I have renewed my development environment and tried to install ApiGen but somehow got dependency issues and unable to install it. We should find another documentation generator and host those generated files on GitHub Pages so we can leave search functionality to search engines like Google, Bing, DuckDuckGo and so on. This way, collaborators can update the documentation whenever possible.

The reason I used ApiGen 2.8.0 is that it supported the @package annotation to be parsed like @package AdminPageFramework/Utility and create corresponding sub-sections in the resulted pages. When I tried some tools several years ago, most of them did not support it.

We have to find a good documentation generator first. If you find a good one, let me know. If we cannot find a good one, then I have another idea.

mrtwebdesign commented 1 month ago

The search isn't useful. I haven't used the framework before but it reminds me a bit of CMB2. The previous dev that made a plugin using it sets up fields with "addSettingField". That should be easy to look up, but it's not indexed at all. I should be able to look up a method or function by name and I get nothing. I noted above you are falling back on having people use Google and so on. How about letting people know up front they may need to do that?