Improve readme files for users and developers

bobbingwide / sb-children-block

List children of the current content as links.

2 stars 0 forks source link

Improve readme files for users and developers #11

Closed bobbingwide closed 11 months ago

bobbingwide commented 4 years ago

@andrewmleonard made some comments about the readme.txt file

How do I install the block?
Why do I need to know about build routines?

Good questions.

1. How do I install the block?

We had a look at the Block Directory Search and came across a few failings in the search. I demonstrated what happens when you search for the block, typing in the letters of the block title one by one: c-h-i-l-d-r-e-n I documented them in my blog. See "Finding and installing the Children block" in https://herbmiller.me/sb-children-block-my-first-single-block-plugin/

Some failings have already been documented as Gutenberg issues. I'm going to try to take advantage of the others by improving the readme.

2. Why do I need to know about the build routines?

You don't unless you want to build the code yourself. So, I'll move this documentation to a readme.md file in the src folder.

bobbingwide commented 4 years ago

Trying to follow my new instructions on cwiccer.com I found the block but when I clicked on Add block an error message was displayed in the block inserter. I'll need to repeat the experiment to reproduce then analyze the problem.

bobbingwide commented 4 years ago

I reproduced the problem in cwiccer.com and herbmiller.me but don't yet know the cause of the problem. I think this should be a separate issue.

bobbingwide commented 4 years ago

Having improved the readme.txt file in v1.0.1 we now get different results. It's a lot easier to find the block. Basically I've implemented the equivalent of the black hat technique of keyword stuffing. I don't think this is what WordPress.org would want. I've updated my findings in https://herbmiller.me/sb-children-block-my-first-single-block-plugin/ I think I should raise an issue against Gutenberg.

bobbingwide commented 4 years ago

Now that WordPress 5.5 has been released I retested the installation

On a new site I searched for sb and the block/plugin was listed.
Then I clicked on Add block and the plugin was installed and the block added to the page.
The Add block button wasn't disabled though.
Clicking on it again displayed "This block is already installed. Try reloading the page."
I reloaded the page and searched for sb again.
The response was "No blocks found in your library. These blocks can be downloaded and installed.
And SB Children block was the only block listed again.

bobbingwide commented 4 years ago

I think I should raise an issue against Gutenberg.

I discussed this briefly on Slack and said I might raise an issue entitled Block Directory Search susceptible to keyword stuffing.

I haven't raised it yet.

bobbingwide commented 3 years ago

The latest situation is that I can no longer find the SB Children block using the block directory search. I don't know why not. I've asked on the #pluginreview channel. https://wordpress.slack.com/archives/C1LBM36LC/p1604166543315800

bobbingwide commented 3 years ago

I also asked in #meta. Dion Hulse replied

It looks like it might’ve dropped out the of the search index for some reason, unsure why, I’ve removed it from the block directory, and then re-added it (like you attempted it looks like) and it should now show up.

Re: like you attempted. I did recheck the zip file and got told it was already in the block directory. Hence the questions.

bobbingwide commented 2 years ago

With the current version of the block, v1.1.0, the problem with installing in the editor doesn't occur any more. There's a new version coming, v1.2.0. I'll need to retest when it's on wordpress.org

bobbingwide commented 11 months ago

v1.2.3 now available with an updated src/README.md