search

Automattic / wp-calypso

The JavaScript and API powered WordPress.com
https://developer.wordpress.com
GNU General Public License v2.0
12.41k stars 1.98k forks source link

Help Center: Extend contextual help with tailored posts #88707

Closed escapemanuele closed 5 months ago

escapemanuele commented 6 months ago

Context: https://github.com/Automattic/wp-calypso/issues/88555#issuecomment-2008597765

In the Help Center we offer contextual docs based on the url we are in. We have this list here: https://github.com/Automattic/wp-calypso/blob/trunk/packages/help-center/src/route-to-query-mapping.json

It would be nice also to offer the possibility of specifying a tailored list of post ids to show when on a certain url.

Check if tailored post ids exist should happen here: https://github.com/Automattic/wp-calypso/blob/trunk/packages/help-center/src/hooks/use-context-based-search-mapping.tsx#L13

Take also locale into consideration. (different support sites have different ids for the same article in different languages)

Algo could be:

  1. Search for a tailored list of ids, if it exists show it.
  2. Otherwise fallback to contextual search as before.
renancarvalho commented 6 months ago

Hi @donalirl, regarding this issue, Is this tailored article structure something that makes sense to you?

{
    "/home/": [ { "locale": "en", "post_ids": [ 248292, 150414 ], "blog_id": 9619154 } ],
    "/posts/": [ { "locale": "en", "post_ids": [ 4458, 4744 ], "blog_id": 9619154 } ],
    "/media/": [ { "locale": "en", "post_ids": [ 99385, 99879, 99982 ], "blog_id": 33534099 } ],
    "/wp-admin/post-new.php": [
        { "locale": "en", "post_ids": [ 99385, 99879, 99982 ], "blog_id": 33534099 }
    ]
}

Which means, on /home, in English, we show in the HelpCenter post IDs 248292, 150414 from blog ID 9619154 and so on.

PS: I am still understanding if the locale is really necessary since the blog_id is already by locale.

This is a draft structure that I have been working on here https://github.com/Automattic/wp-calypso/pull/88808, soon you will be able to test.

Please let me know your thoughts. 👍

donalirl commented 6 months ago

Yes, makes sense to me! Will this be an MC tool, or would we submit the tailored list to you in the format above, or some other process?

renancarvalho commented 6 months ago

or would we submit the tailored list to you in

I think for now you can send it to me/vertex. Soon also plan something on MC, WDYT @escapemanuele ?

escapemanuele commented 6 months ago

Yes, let's keep this simple as the first iteration, it will take little for us to update the list.

Then we can think of a more structured way of course 👍

renancarvalho commented 6 months ago

@donalirl you can take this https://github.com/Automattic/wp-calypso/blob/trunk/packages/help-center/src/route-to-query-mapping.json as an example and inspiration for all the routes we have. Please let me know if you have any questions or doubts 👍

donalirl commented 5 months ago

@renancarvalho Here's a work-in-progress of what I've done so far (don't upload it yet!) I just want to check with you:

  1. Have I formatted it correctly?
  2. If a page is no longer public (we retire the article by making it private), will it continue to appear publicly with the label 'private' in the title (like what happened in peCdcN-fr-p2? Or will it fall back to a default suggestion?
{
    "/home/": "home",
    "/stats/": [ { "locale": "en", "post_ids": [ 276080, 3307, 276101, 4454, 98905], "blog_id": 9619154 } ],
    "/add-ons/": "add-ons",
    "/mailboxes": [ { "locale": "en", "post_ids": [ 34087], "blog_id": 9619154 } ],
    "/comments/": "comments",
    "/checkout/": [ { "locale": "en", "post_ids": [ 100856, 199786, 267108, 1988, 267100], "blog_id": 9619154 } ],
    "/backup/": "backup",
    "/themes/": "themes",
    "/plugins/manage": "manage plugins",
    "/plugins": "plugins",
    "/plans/": "upgrade plan",
    "/email/": "manage emails",
    "/domains/manage":  { "locale": "en", "post_ids": [ 2784, 137759, 2789, 185130, 1988], "blog_id": 9619154 } ],
    "/media/": [ { "locale": "en", "post_ids": [ 853, 3749, 152893, 4744, 1998 ], "blog_id": 9619154 } ],
    "/posts/drafts": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 1668, 14812 ], "blog_id": 9619154 } ],
    "/posts/scheduled": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 1344, 82 ], "blog_id": 9619154 } ],
    "/posts/trashed": [ { "locale": "en", "post_ids": [ 100846, 193593, 176675, 5182, 82 ], "blog_id": 9619154 } ],
    "/posts/": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 191604, 82 ], "blog_id": 9619154 } ],
    "/posts": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 191604, 82 ], "blog_id": 9619154 } ],
    "/pages/drafts": [ { "locale": "en", "post_ids": [ 86, 1668, 163330, 14812, 189860 ], "blog_id": 9619154 } ],
    "/pages/scheduled": [ { "locale": "en", "post_ids": [ 86, 1344, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/pages/trashed": [ { "locale": "en", "post_ids": [ 86, 5182, 163330, 193593, 189860 ], "blog_id": 9619154 } ],
    "/pages/": [ { "locale": "en", "post_ids": [ 86, 1698, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/pages": [ { "locale": "en", "post_ids": [ 86, 1698, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/purchases/subscriptions/": [ { "locale": "en", "post_ids": [ 111341, 80135, 151483, 40792, 1988 ], "blog_id": 9619154 } ],
    "/purchases/payment-methods/": [ { "locale": "en", "post_ids": [ 111341, 80135, 76237, 40792, 1988 ], "blog_id": 9619154 } ],
    "/purchases/billing-history/": [ { "locale": "en", "post_ids": [ 111341, 80135, 234670, 40792, 1988 ], "blog_id": 9619154 } ],
    "/activity-log/": "activity",
    "/woocommerce": "woocommerce",
    "/wp-admin/admin.php?page=wc": "woocommerce",
    "/people/team": "site users",
    "/people/new": "invite user",
    "/subscribers": "subscribers",
    "/me/security": "security",
    "/me/purchases": [ { "locale": "en", "post_ids": [ 111341, 80135, 276100, 40792, 1988 ], "blog_id": 9619154 } ],
    "/me/privacy": "privacy",
    "/me/notifications": "notification settings",
    "/me/account": "account settings",
    "/me/site-blocks": "blocked sites",
    "/me/get-apps": "wordpress apps",
    "/me": "my profile",
    "/settings/general/": "general settings",
    "/settings/writing/": "writing settings",
    "/settings/reading/": "reading settings",
    "/settings/newsletter/": "newsletter settings",
    "/settings/performance/": "performance settings",
    "/settings/taxonomies/category/": "site categories",
    "/settings/taxonomies/post_tag/": "post tag",
    "/settings/podcasting/": "podcasting",
    "/hosting-config/": "hosting configuration",
    "/wp-admin/options-media.php": "media settings",
    "/wp-admin/edit.php?post_type=jetpack-testimonial": "testimonials",
    "/wp-admin/edit.php?post_type=page": "pages",
    "/wp-admin/edit.php?post_type=feedback": "feedback form",
    "/wp-admin/edit.php": "posts",
    "/wp-admin/post-new.php?post_type=jetpack-testimonial": "new testimonial",
    "/wp-admin/post-new.php?post_type=page": "new page",
    "/wp-admin/post-new.php": "new post",
    "/wp-admin/admin.php?page=akismet-key-config": "site spam",
    "/wp-admin/admin.php?page=jetpack-search": "jetpack search",
    "/wp-admin/admin.php?page=polls": "crowdsignal",
    "/wp-admin/admin.php?page=ratings": "ratings",
    "/wp-admin/options-general.php?page=debug-bar-extender": "debug bar extender",
    "/wp-admin/index.php?page=my-blogs": "my sites",
    "/read/conversations": "conversations",
    "/read/notifications": "notifications",
    "/read/subscriptions": "manage subscriptions",
    "/read/list": "reader list",
    "/read/search": "search",
    "/read": "reader",
    "/discover": "discover blogs",
    "/tags": "tags",
    "/sites": "manage sites",
    "/marketing/tools/": "marketing tools",
    "/marketing/traffic/": "traffic",
    "/marketing/connections/": "connections",
    "/marketing/sharing-buttons/": "social share",
    "/marketing/business-tools/": "business tools",
    "/earn/": "monetize",
    "/advertising/": "advertising",
    "/import/": "import",
    "/export/": "export"
}
renancarvalho commented 5 months ago

Hi @donalirl, The structure looks good, although, for this change, it is only necessary the tailored articles (the ones with the post_ids and blog_ids).

For instance, /home/,/add-ons/,/backup/ we can let it out because these are already here

We have another file just handling the tailored ones like "/checkout/": [ { "locale": "en", "post_ids": [ 100856, 199786, 267108, 1988, 267100], "blog_id": 9619154 } ], "/mailboxes": [ { "locale": "en", "post_ids": [ 34087], "blog_id": 9619154 } ],

Regarding the retired articles question, I have to check, do you have a retire article example?

If you would like to test/see it, I can create a test PR with this structure, then you should be able to see it.

Please let me know if you have any other questions.

escapemanuele commented 5 months ago

@donalirl the structure @renancarvalho has created lets you define, for a particular URL, both tailored articles or the query to search for. And we give priority to the tailored articles. So if you for a certain page specify 2 tailored articles and also a query, you'll see a total of 5 articles: 2 tailored and 3 returned from the search for that query.

donalirl commented 5 months ago

Thank you! Here's a complete list of tailored suggestions:

{
    "/home/": [ { "locale": "en", "post_ids": [ 1988, 158974, 134698, 1507, 147594], "blog_id": 9619154 } ],
    "/stats/": [ { "locale": "en", "post_ids": [ 276080, 3307, 276101, 4454, 98905], "blog_id": 9619154 } ],
    "/mailboxes": [ { "locale": "en", "post_ids": [ 34087], "blog_id": 9619154 } ],
    "/checkout/": [ { "locale": "en", "post_ids": [ 100856, 199786, 267108, 1988, 267100], "blog_id": 9619154 } ],
    "/backup/": [ { "locale": "en", "post_ids": [ 145800, 159843, 115025, 151496, 134940 ], "blog_id": 9619154 } ],
    "/themes/": [ { "locale": "en", "post_ids": [ 2278, 184023, 188667, 259706, 294101 ], "blog_id": 9619154 } ],
    "/domains/manage":  { "locale": "en", "post_ids": [ 2784, 137759, 2789, 185130, 1988], "blog_id": 9619154 } ],
    "/media/": [ { "locale": "en", "post_ids": [ 853, 3749, 152893, 4744, 1998 ], "blog_id": 9619154 } ],
    "/posts/drafts": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 1668, 14812 ], "blog_id": 9619154 } ],
    "/posts/scheduled": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 1344, 82 ], "blog_id": 9619154 } ],
    "/posts/trashed": [ { "locale": "en", "post_ids": [ 100846, 193593, 176675, 5182, 82 ], "blog_id": 9619154 } ],
    "/posts/": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 191604, 82 ], "blog_id": 9619154 } ],
    "/posts": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 191604, 82 ], "blog_id": 9619154 } ],
    "/pages/drafts": [ { "locale": "en", "post_ids": [ 86, 1668, 163330, 14812, 189860 ], "blog_id": 9619154 } ],
    "/pages/scheduled": [ { "locale": "en", "post_ids": [ 86, 1344, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/pages/trashed": [ { "locale": "en", "post_ids": [ 86, 5182, 163330, 193593, 189860 ], "blog_id": 9619154 } ],
    "/pages/": [ { "locale": "en", "post_ids": [ 86, 1698, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/pages": [ { "locale": "en", "post_ids": [ 86, 1698, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/purchases/subscriptions/": [ { "locale": "en", "post_ids": [ 111341, 80135, 151483, 40792, 1988 ], "blog_id": 9619154 } ],
    "/purchases/payment-methods/": [ { "locale": "en", "post_ids": [ 111341, 80135, 76237, 40792, 1988 ], "blog_id": 9619154 } ],
    "/purchases/billing-history/": [ { "locale": "en", "post_ids": [ 111341, 80135, 234670, 40792, 1988 ], "blog_id": 9619154 } ],
    "/activity-log/": [ { "locale": "en", "post_ids": [ 145800, 159843, 115025, 151496, 134940 ], "blog_id": 9619154 } ],
    "/people/team": [ { "locale": "en", "post_ids": [ 1221, 226531, 5444, 80368, 10977 ], "blog_id": 9619154 } ],
    "/people/new": [ { "locale": "en", "post_ids": [ 1221, 226531, 5444, 80368, 10977 ], "blog_id": 9619154 } ],
    "/me/security": [ { "locale": "en", "post_ids": [ 89, 80368, 58847, 10977, 91 ], "blog_id": 9619154 } ],
    "/me/purchases": [ { "locale": "en", "post_ids": [ 111341, 80135, 276100, 40792, 1988 ], "blog_id": 9619154 } ],
    "/me/account": [ { "locale": "en", "post_ids": [ 91, 80368, 9394, 134698, 2116 ], "blog_id": 9619154 } ],
    "/me": [ { "locale": "en", "post_ids": [ 19775, 80368, 9394, 134698, 2116 ], "blog_id": 9619154 } ],
    "/settings/general/": [ { "locale": "en", "post_ids": [ 1501, 119826, 1507, 134940, 240668 ], "blog_id": 9619154 } ],
    "/settings/newsletter/": [ { "locale": "en", "post_ids": [ 257112, 67810, 168381, 220199, 5444 ], "blog_id": 9619154 } ],
    "/wp-admin/edit.php?post_type=page": [ { "locale": "en", "post_ids": [ 86, 1698, 163330, 124077, 189860 ], "blog_id": 9619154 } ],
    "/wp-admin/edit.php": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 191604, 82 ], "blog_id": 9619154 } ],
    "/wp-admin/post-new.php?post_type=page":  [ { "locale": "en", "post_ids": [ 86, 1698, 163330, 124077, 147594 ], "blog_id": 9619154 } ],
    "/wp-admin/post-new.php": [ { "locale": "en", "post_ids": [ 100846, 84, 176675, 191604, 147594 ], "blog_id": 9619154 } ],
    "/marketing/tools/": [ { "locale": "en", "post_ids": [ 216472, 152657, 121282, 5022, 3077 ], "blog_id": 9619154 } ],
    "/marketing/traffic/": [ { "locale": "en", "post_ids": [ 155209, 98905, 142, 134940, 5022 ], "blog_id": 9619154 } ],
    "/marketing/connections/": [ { "locale": "en", "post_ids": [ 216472, 152893, 152657, 77589, 320228 ], "blog_id": 9619154 } ],
    "/earn/": [ { "locale": "en", "post_ids": [ 120172, 154292, 169123, 255352, 3307 ], "blog_id": 9619154 } ],
    "/import/": { "locale": "en", "post_ids": [ 41, 240055, 137759 ], "blog_id": 9619154 } ],
    "/export/": { "locale": "en", "post_ids": [ 2087, 278472, 159843 ], "blog_id": 9619154 } ],
}

I've omitted some of the original list where the keyword was enough to produce helpful suggestions.

I'm happy to test these once they go live.

donalirl commented 5 months ago

Regarding the retired articles question, I have to check, do you have a retire article example?

Yes. While checking through the screens, I discovered some private pages are currently showing up in the Help Center. See peCdcN-fr-p2#comment-1721

github-actions[bot] commented 5 months ago

Support References

This comment is automatically generated. Please do not edit it.

donalirl commented 5 months ago

2. If a page is no longer public (we retire the article by making it private), will it continue to appear publicly with the label 'private' in the title (like what happened in peCdcN-fr-p2? Or will it fall back to a default suggestion?

I confirmed that if we retire one of the tailored articles, it will continue to appear publicly with the label 'private'. While I don't expect we will retire a tailored article often, it actually happened for post_ID 1501 in https://github.com/Automattic/en.support-docs-content/issues/2446#issuecomment-2063827173

We've made the article public again for now. @renancarvalho would you mind updating the following line? These are the new valid IDs:

"/settings/general/": [ { "locale": "en", "post_ids": [ 185130, 119826, 1507, 134940, 240668 ], "blog_id": 9619154 } ],
escapemanuele commented 5 months ago

@donalirl I think we'll have the indexing fixed soon, as in peCdcN-fr-p2#comment-1750. Then I hope that the retired articles won't show again 👍

renancarvalho commented 5 months ago

This has been updated and deployed 👍
Closing the issue :)