-
Notifications
You must be signed in to change notification settings - Fork 216
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add the IP for machine generated tags on the frontend
Signed-off-by: Olga Bulat <obulat@gmail.com>
- Loading branch information
Showing
1 changed file
with
199 additions
and
0 deletions.
There are no files selected for viewing
199 changes: 199 additions & 0 deletions
199
...ekognition_data/20240510-implementation_plan_machine_generated_tags_frontend.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,199 @@ | ||
| # 2024-05-08 Implementation Plan: Machine-generated tags in the frontend | ||
|
|
||
| **Author**: @obulat | ||
|
|
||
| <!-- See the implementation plan guide for more information: https://github.com/WordPress/openverse/tree/19791f51c063d0979112f4b9f4eeace04c8cf5ff/docs/projects#implementation-plans-status-in-rfc --> | ||
| <!-- This template is exhaustive and may include sections which aren't relevant to your project. Feel free to remove any sections which would not be useful to have. --> | ||
|
|
||
| ## Reviewers | ||
|
|
||
| <!-- Choose two people at your discretion who make sense to review this based on their existing expertise. Check in to make sure folks aren't currently reviewing more than one other proposal or RFC. --> | ||
|
|
||
| - [ ] @zackkrida | ||
| - [ ] @AetherUnbound | ||
|
|
||
| ## Project links | ||
|
|
||
| <!-- Enumerate any references to other documents/pages, including milestones and other plans --> | ||
|
|
||
| - [Project Thread](https://github.com/WordPress/openverse/issues/431) | ||
| - [Project Proposal](/projects/proposals/rekognition_data/20240320-project_proposal_rekognition_data.md) | ||
|
|
||
| ## Overview | ||
|
|
||
| <!-- An overview of the implementation plan, if necessary. Save any specific steps for the section(s) below. --> | ||
|
|
||
| This implementation plan will describe how we plan to display the | ||
| machine-generated tags separately from the source tags on the single result | ||
| page. All tags will be clickable and lead to a collection view by the selected | ||
| tag. The tag collection view will not be affected as we will not show different | ||
| results for a machine-generated tag than the source tag. | ||
|
|
||
| ## Expected Outcomes | ||
|
|
||
| <!-- List any succinct expected products from this implementation plan. --> | ||
|
|
||
| When this work is completed, the single result page will display | ||
| machine-generated tags separately from the source tags. For machine-generated | ||
| tags, we will also display the tag provider and its accuracy. | ||
|
|
||
| ## Step-by-step plan | ||
|
|
||
| <!-- | ||
| List the ordered steps of the plan in the form of imperative-tone issue titles. | ||
| The goal of this section is to give a high-level view of the order of implementation any relationships like | ||
| blockages or other dependencies that exist between steps of the plan. Link each step to the step description | ||
| in the following section. | ||
| If special deployments are required between steps, explicitly note them here. Additionally, highlight key | ||
| milestones like when a feature flag could be made available in a particular environment. | ||
| --> | ||
|
|
||
| 1. [Create a wrapper component that displays the tags in two sections: source-provided and machine generated](#create-a-wrapper-vmediatags-component) | ||
| 2. [Add a page that describes the machine-generated and source tags.](#add-about-tags-description-page) | ||
|
|
||
| ## Step details | ||
|
|
||
| <!-- | ||
| Describe all of the implementation steps listed in the "step-by-step plan" in detail. | ||
| For each step description, ensure the heading includes an obvious reference to the step as described in the | ||
| "step-by-step plan" section above. | ||
| --> | ||
|
|
||
| ### Create a wrapper `VMediaTags` component | ||
|
|
||
| This component will handle filtering the tags into two sets: machine-generated | ||
| and source-provided. It will also display the headings and the link to the | ||
| "About tags" page. A new child component, `VCollapsibleTagSection`, will handle | ||
| displaying of the tags in several rows, collapsing them if there are more than | ||
| three rows of tags. | ||
|
|
||
| Currently, we deduplicate all tags to only display unique tags. When we display | ||
| the tags by generation type, there will probably be duplicates between the | ||
| source and the generated tags. However, each section individually will still be | ||
| normalized to prevent duplicates. | ||
|
|
||
| The generated tags section should split the tags by different providers into | ||
| subsections, and should use the provider of the tag as the section label. For | ||
| instance, if there are tags by both `recognition` and `clarifai`, there will be | ||
| two sub-sections in the Generated tags section: tags generated by `recognition` | ||
| and tags generated by `clarifai`. In the future, if there are more providers, | ||
| there could be more tag sections. The tags in each subsection will be ordered by | ||
| their accuracy. | ||
|
|
||
| There is no need to create a separate component for machine-generated tags, the | ||
| slot will enable us to display the additional accuracy information. | ||
|
|
||
| ### Add "About tags" description page | ||
|
|
||
| We should add a page to explain the users the difference between where the | ||
| Openverse tags come from, the difference between the source and generated tags, | ||
| and a short description of the machine-generated tag providers. This page should | ||
| be linked from the Generated tags section. | ||
|
|
||
| ## Dependencies | ||
|
|
||
| This project needs the API to add the `unstable__provider` property to tags in | ||
| media responses, which was implemented in | ||
| [Expose provider in the API tags response #4280](https://github.com/WordPress/openverse/pull/4280) | ||
|
|
||
| ### Feature flags | ||
|
|
||
| <!-- List feature flags/environment variables that will be utilised in the development of this plan. --> | ||
|
|
||
| The project will contain at most 2 PRs that can be reverted, so the feature | ||
| flags are not necessary. | ||
|
|
||
| ### Infrastructure | ||
|
|
||
| <!-- Describe any infrastructure that will need to be provisioned or modified. In particular, identify associated potential cost changes. --> | ||
|
|
||
| No infrastructure changes will be necessary, we will only update the single | ||
| result pages of the Nuxt frontend. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| <!-- Describe any alternatives considered and why they were not chosen or recommended. --> | ||
|
|
||
| The tags will be displayed in two sections: "Source tags" and "Generated tags". | ||
|
|
||
| For the machine-generated tags, we want to add a link to the page that describes | ||
| We have the provider (currently, it will be "clarifai" and "rekognition") and | ||
| the accuracy data for the machine-generated providers. | ||
|
|
||
| There are several options of displaying these properties. | ||
|
|
||
| 1. Do not display this data. The two tags sections will be identical. | ||
| 2. The generated tags will have a tooltip that displays the tag's provider and | ||
| its accuracy. | ||
| 3. Display generated tags in sections by provider so that we don't duplicate the | ||
| tag provider on each tag. Then, on each tag, display the accuracy. | ||
|
|
||
| The first option is the simplest to implement, however, it fails to provide | ||
| the fullest information to the users. The second option provides the accuracy | ||
| and provider information to the user, however it is not very accessible. | ||
| Different browsers and screen readers treat the tooltips differently. We have | ||
| enough room on the page to display this data in full, using the third option: | ||
| labelling all the tags generated by a single provider with a "by provider" | ||
| heading, and adding the accuracy to the tag's inner content. This way, the | ||
| user will see the provider and the accuracy of the tag without any additional | ||
| actions. As a bonus, if a tag is generated by multiple providers, the user | ||
| will see that different providers generate the same tag, and will be able to | ||
| see the difference in accuracy between the providers. | ||
|
|
||
| ## Design | ||
|
|
||
| <!-- Note any design requirements for this plan. --> | ||
|
|
||
| The first iteration of the designs that use the first alternative option is | ||
| ready: | ||
| [Displaying machine-generated content](https://github.com/WordPress/openverse/issues/4192) | ||
| If we decide to go with the third alternative option, we will need to add the | ||
| provider headings and the accuracy to the tags. | ||
|
|
||
| ## Blockers | ||
|
|
||
| <!-- What hard blockers exist that prevent further work on this project? --> | ||
|
|
||
| There are no blockers for this work. | ||
|
|
||
| ## Accessibility | ||
|
|
||
| <!-- Are there specific accessibility concerns relevant to this plan? Do you expect new UI elements that would need particular care to ensure they're implemented in an accessible way? Consider also low-spec device and slow internet accessibility, if relevant. --> | ||
|
|
||
| Adding the "Source tags" and "Generated tags" headings is good for the | ||
| accessibility of the tag list. Both the sighted and the screen reader users will | ||
| understand what the list is for. It is always desirable to have visible label | ||
| next to a list of elements. | ||
|
|
||
| The display of generated tags' provider and accuracy is, on the other hand, a | ||
| challenging problem from accessibility standpoint. Tooltips are often described | ||
| as inaccessible for mobile users who do not have a hover action. MDN's section | ||
| on tooltip best practices suggests providing "clear labels and sufficient body | ||
| text" instead of tooltips that hide important information. We could add the tag | ||
| accuracy to the However, if we decide to add the provider to the generated tags, | ||
| there will be a lot of duplication. | ||
|
|
||
| ## Rollback | ||
|
|
||
| <!-- How do we roll back this solution in the event of failure? Are there any steps that can not easily be rolled back? --> | ||
|
|
||
| We can roll back this solution by reverting the PRs implementing this. | ||
|
|
||
| ## Localization | ||
|
|
||
| <!-- Any translation or regional requirements? Any differing legal requirements based on user location? --> | ||
|
|
||
| The tag headings will be translated as usual. For the "About page" it is | ||
| important to split the text into shorter chunks to make them easier to handle | ||
| for translators. The eslint rule will make sure that this is done properly. | ||
|
|
||
| ## Risks | ||
|
|
||
| <!-- What risks are we taking with this solution? Are there risks that once taken can’t be undone?--> | ||
|
|
||
| ## Prior art | ||
|
|
||
| <!-- Include links to documents and resources that you used when coming up with your solution. Credit people who have contributed to the solution that you wish to acknowledge. --> |