[wp-meta] [Making WordPress.org] #7530: More relevant block editor handbook search

[Making WordPress.org]

#7530: More relevant block editor handbook search
---------------------------+--------------------
 Reporter:  gaambo         |      Owner:  (none)
     Type:  enhancement    |     Status:  new
 Priority:  normal         |  Milestone:
Component:  Developer Hub  |   Keywords:
---------------------------+--------------------
 I really like the new design of the block editor handbook, but after using
 it a lot, I've got some feedback/ideas for better search experience:

 **1. Add keyboard shortcut for searching**
 On long pages (like a [https://developer.wordpress.org/block-editor
 /reference-guides/packages/packages-data/ package reference]), when you
 have scrolled down very far, getting back to the search field can be
 cumbersome. There's no "back to top" button and no keyboard shortcut for
 using the search field.
 A lot of developer documentation provide a Ctrl+K keyboard shortcut to
 open a search overlay or move focus to the search field. An "internal"
 example is [https://wordpress.github.io/wordpress-playground/ the
 WordPress Playground documentation] and another one
 [https://tailwindcss.com/ tailwind CSS].
 I often find myself switching between different packages/references, and
 the block editor handbook with references for each package has a very big
 navigation menu - so anything that makes navigation easier with keyboard
 would be great.

 **2. Search Results: show matched text / jump to match**

 When searching for any keyword, the results do not show how/where the
 keyword was matched. When clicking on the result, the page opens at the
 top - requiring the user to use Ctrl+F on the page again. This once again
 relates to the references and pages being very long and therefore finding
 the matched keyword/paragraph hard.

 Example: Search for [https://developer.wordpress.org/block-
 editor/?s=useinnerblocksprops useInnerBlocksProps]. The first result is
 [https://developer.wordpress.org/block-editor/reference-guides/packages
 /packages-block-editor/ the @wordpress/block-editor package reference] and
 [https://developer.wordpress.org/block-editor/reference-guides/packages
 /packages-block-editor/#useinnerblocksprops useInnerBlocksProps] is at the
 very bottom of the page but the page loads at the top.

 [[Image(block-editor-handbook-results-innerblocks.png)]]

 I suggest two things:
 - Add an excerpt of the matched text/paragraph to the results view and use
 some styling (e.g. background color, bold) to highlight the keyword.
 - When clicking on the result, jump to the paragraph/headline the matched
 text was first found in.

 **3. More relevant search results**
 I don't know how the search results are sorted at the moment, but often
 times I find the more related results at the bottom instead of the top.
 Maybe we could add some "weights" to keywords? I don't know any technical
 details - if the editor handbook is built on a standard WP search - but a
 lot of developer documentation use algolia for that (again the
 [https://wordpress.github.io/wordpress-playground/ WordPress Playground
 docs] are an example for that).
 Or maybe usage of a keyword in a headline is more relevant than in a code
 example? We could also categorize the results into "API reference",
 "guides" (just like the main navigation bar on the side)

 Examples:

 - Search for [https://developer.wordpress.org/block-
 editor/?s=getentityrecords getEntityRecords]. The first result is the
 [https://developer.wordpress.org/block-
 editor/contributors/code/deprecations/ Deprecations] page. Which may be
 relevant, but I guess if I search for the exact method name, I'd want to
 see the documentation of that method, not of any deprecations. The next
 result is @wordpress/data - which just has an example of using the
 function, but not the docs. The real documentation of the function is
 actually just the fifth element.

 [[Image(block-editor-handbook-results-entityrecords.png)]]

 - Search for [https://developer.wordpress.org/block-
 editor/?s=useblockprops useBlockProps]. "Edit and Save" (4th), "The block
 wrapper" (5th) and the package (@wordpress/block-editor, 8th) are not the
 top results. Actually, "RichText Reference" comes before, which seems very
 unrelated.

 I've encountered this many times, but did not write down all the examples.
 I will extend this list of examples.

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/7530>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org