Docs: new review UI guide (#5083)

nataliaElv · dvsrepo · pre-commit-ci[bot] · web-flow · commit 8ae4c739b80b · 2024-06-21T16:34:03.000+02:00
# Pull Request Template  Closes #<issue_number> **Type of change**  - Documentation update **How Has This Been Tested**  **Checklist**  - I added relevant documentation - follows the style guidelines of this project - I did a self-review of my code - I made corresponding changes to the documentation - I confirm My changes generate no new warnings - I have added tests that prove my fix is effective or that my feature works - I have added relevant notes to the CHANGELOG.md file (See https://keepachangelog.com/) --------- Co-authored-by: Daniel Vila Suero <daniel@argilla.io> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
diff --git a/argilla/docs/how_to_guides/annotate.md b/argilla/docs/how_to_guides/annotate.md
@@ -3,48 +3,47 @@ description: In this section, we will provide a step-by-step guide to show how t
 ---
 # Annotate your dataset
 
-!!! note
-    To experience the UI features firsthand, you can take a look to the [Demo ↗](https://demo.argilla.io/sign-in?auth=ZGVtbzoxMjM0NTY3OA==).
+!!! note ""
+    To experience the UI features firsthand, you can take a look at the [Demo ↗](https://demo.argilla.io/sign-in?auth=ZGVtbzoxMjM0NTY3OA==).
 
 Argilla UI offers many functions to help you manage your annotation workflow, aiming to provide the most flexible approach to fit the wide variety of use cases handled by the community.
 
 ## Annotation interface overview
 
 ### Flexible layout
 
-=== "The header"
+![UI overview](../assets/images/how_to_guides/annotate/ui_overview.png)
 
-    At the right side of the navigation breadcrumb, you can customize the dataset settings and edit your profile.
+The UI is responsive with two columns for larger devices and one column for smaller devices. This enables you to annotate data using your mobile phone for simple datasets (i.e., not very long text and 1-2 questions) or resize your screen to get a more compact UI.
 
-=== "The left pane"
+=== "Header"
 
-    This area is displayed on top of **the control panel** for performing searches, applying filters and sorting results. The record card(s) are displayed one by one or in a vertical list depending on the active view: **Focus view** or **Bulk view.** A card includes one or many fields and an ellipsis menu to mainly access the record extra info like the metadata.
+    At the right side of the navigation breadcrumb, you can customize the dataset settings and edit your profile.
 
-=== "The right pane"
+=== "Left pane"
+    This area displays the **control panel** on the top. The control panel is used for performing keyword-based search, applying filters, and sorting the results.
 
-    This is where you annotate your dataset. Simply fill it out as a form, then choose to Submit, Save as Draft, or Discard your response to send the records to their corresponding queues.
+    Below the control panel, the record card(s) are displayed one by one (Focus view) or in a vertical list (Bulk view).
 
-=== "The left bottom panel"
+=== "Right pane"
 
-    This expandable area displays the annotation guidelines.
+    This is where you annotate your dataset. Simply fill it out as a form, then choose to `Submit`, `Save as Draft`, or `Discard`.
 
-=== "The right bottom panel"
+=== "Left bottom panel"
 
-    This expandable area displays your annotation progress.
+    This expandable area displays the annotation guidelines. The annotation guidelines can be edited by owner and admin roles in the dataset settings.
 
-![UI overview](../assets/images/how_to_guides/annotate/ui_overview.png)
+=== "Right bottom panel"
 
-!!! tip
-    The app is responsive which enable you to adapt your workspace from two to one column. You can even use your mobile to provides simple feedback on your datasets.
+    This expandable area displays your annotation progress.
 
 ### Shortcuts
 
-Argilla UI includes a range of shortcuts. For the main actions submit, discard, save as draft and the labels the keys are showed in the button.
+The Argilla UI includes a range of shortcuts. For the main actions (submit, discard, save as draft and selecting labels) the keys are showed in the corresponding button.
 
-To move from one question to another or between records using the keyboard take a look at the table below.
+To learn how to move from one question to another or between records using the keyboard, take a look at the table below.
 
-!!! tip
-    Shortcuts provide a smoother experience, especially with a long list of labels or single-question forms.
+Shortcuts provide a smoother annotation experience, especially with datasets using a single question (Label, MultiLabel, Rating, or Ranking).
 
 ??? "Available shortcuts"
 
@@ -77,23 +76,20 @@ If you are starting an annotation effort, all the records are initially kept in
 
 ### Suggestions
 
-If your dataset includes model predictions, you will see them represented by a sparkle icon `✨` in the label or value button. We call them “Suggestions” and they appear in the form as pre-filled responses. If you agree with the suggestion, you just need to click on the Submit button, and they will be considered as your response.
+If your dataset includes model predictions, you will see them represented by a sparkle icon `✨` in the label or value button. We call them “Suggestions” and they appear in the form as pre-filled responses. If confidence scores have been included by the dataset admin, they will be shown alongside with the label. Additionally, admins can choose to always show suggested labels at the beginning of the list. This can be configured from the dataset settings.
 
-If the suggestion is incorrect, you can modify it and submit your response.
-
-The score per suggested label/value is displayed for MultiLabelQuestion and RankingQuestion.
-For label questions, admins can also choose the ordering of labels in the datasets settings. Additionally, admins can choose to always show suggested labels at the beginning of the list.
+If you agree with the suggestions, you just need to click on the `Submit` button, and they will be considered as your response. If the suggestion is incorrect, you can modify it and submit your final response.
 
 ### Focus view
 
-![Focus view](../assets/images/how_to_guides/annotate/focus_view.png)
+![Focus view](../assets/images/how_to_guides/annotate/focus_view.png){ width=10% height=10% }
 
 This is the default view to annotate your dataset linearly, displaying one record after another.
 
 !!! tip
-    You should use this when getting acquainted with a dataset or when the annotation team is very diverse, the topic is generic.
+    You should use this view if you have a large number of required questions or need a strong focus on the record content to be labelled. This is also the recommended view for annotating a dataset sample to avoid potential biases introduced by using filters, search, sorting and bulk labelling.
 
-Once you submit your first response, the next record will appear automatically. To see again your submitted record, just click on prev.
+Once you submit your first response, the next record will appear automatically. To see again your submitted response, just click on `Prev`.
 
 **Navigating through the records**
 
@@ -103,50 +99,45 @@ Each time the page is fully refreshed, the records with modified statuses (Pendi
 
 ### Bulk view
 
-![Bulk view](../assets/images/how_to_guides/annotate/bulk_view.png)
+![Bulk view](../assets/images/how_to_guides/annotate/bulk_view.png){ width=10% height=10% }
 
 The bulk view is designed to speed up the annotation and get a quick overview of the whole dataset.
 
-It displays the records in a vertical list. Once the view is active, some functions from the **control panel** will be available to optimize the records reading. You define the number of records to display by page between `10`, `25`, `50` , `100` and the option to fix the card height by selecting `Expand records` or `Collapse records`.
+The bulk view displays the records in a vertical list. Once this view is active, some functions from the control panel will activate to optimize the view. You can define the number of records to display by page between `10`, `25`, `50`, `100` and whether records are shown with a fixed (`Collapse records`) or their natural height (`Expand records`).
 
 !!! tip
-    You should use this when you have a good understanding of your data and want to apply your knowledge based on things like similarity search, filter patterns, and suggestion score thresholds.
+    You should use this to quickly explore a dataset. This view is also recommended if you have a good understanding of the domain and want to apply your knowledge based on things like similarity and keyword search, filters, and suggestion score thresholds. For a datasets with a large number of required questions or very long fields, the focus view would be more suitable.
 
-!!! note
-    You should consider that bulk view does not show suggestions in bulk view (except for Spans) and will always convert questions to Draft queue when working with multiple question types.
+    With multiple questions, think about using the bulk view to annotate massively one question. Then, you can complete the annotation per record from the draft queue.
 
-!!! tip
-    With multiple questions, think about using the bulk view to annotate massively one question. Then, you can complete the annotation per records from the draft queue.
+!!! note
+    Please note that suggestions are not shown in bulk view (except for Spans) and that you will need to save as a draft when you are not providing responses to all required questions.
 
 ### Annotation progress
 
-=== "General progress view"
-
-    On the dataset list, the global progress of the annotation task from all users is displayed. This is indicated in the `Global progress` column, which shows the number of left records to be annotated, along with a progress bar. The progress bar displays the percentage and number of records submitted, conflicting (i.e., those with overlap), discarded, and pending by hovering your mouse over it.
+The global progress of the annotation task from all users is displayed in the dataset list. This is indicated in the `Global progress` column, which shows the number of records still to be annotated, along with a progress bar. The progress bar displays the percentage and number of records submitted, conflicting (i.e., those with both submitted and discarded responses), discarded and pending by hovering your mouse over it.
 
-=== "Your own progress view"
+You can track your annotation progress in real time from the righ-bottom panel inside the dataset page. This means that, while you are annotating, the progress bar updates as you submit or discard a record. Expanding the panel, the distribution of `Pending`, `Draft`, `Submitted` and `Discarded` responses is displayed in a donut chart.
 
-    You can track your annotation progress in real-time. That means once you are annotating, the progress bar is incrementing in real time each time you submit or discard a record. Expanding the panel, the distribution of `Pending`, `Draft`, `Submitted` and `Discarded` responses is displayed in a donut chart.
+## Use search, filters, and sort
 
-## Discover patterns and speed up your annotation.
-
-The UI offers various features designed to enhance your understanding of data patterns and streamline annotation tasks. Combining filters with bulk annotations can save you and your team hours of time.
+The UI offers various features designed for data exploration and understanding. Combining these features with bulk labelling can save you and your team hours of time.
 
 !!! tip
     You should use this when you are familiar with your data and have large volumes to annotate based on verified beliefs and experience.
 
-### Search and highlight
+### Search
 
-From the **control panel** at the top of the left pane, you can search across the entire dataset or by fields (if you have more than one in your record) and visualize matched results highlighted in color.
+From the **control panel** at the top of the left pane, you can search by keyword across the entire dataset. If you have more than one field in your records, you may specify if the search is to be performed “All” fields or on a specific one. Matched results are highlighted in color.
 
 ### Order by record semantic similarity
 
 You can retrieve records based on their similarity to another record if vectors have been added to the dataset.
 
 !!! note
-    Consult these guides to know how to add vectors to your [dataset](dataset.md) and [records](record.md).
+    Check these guides to know how to add vectors to your [dataset](dataset.md) and [records](record.md).
 
-To initiate a semantic search, click on `Find similar` within the record you wish to use as a reference. If multiple vectors are available, select the desired vector or choose whether to retrieve the most or least similar records.
+To use the search by semantic similarity function, click on `Find similar` within the record you wish to use as a reference. If multiple vectors are available, select the desired vector. You can also choose whether to retrieve the most or least similar records.
 
 The retrieved records are then ordered by similarity, with the similarity score displayed on each record card.
 
@@ -156,29 +147,27 @@ To cancel the search, click on the cross icon next to the reference record.
 
 ### Filter and sort by metadata, responses, and suggestions
 
-<h4>Filter</h4>
+#### Filter
 
 If the dataset contains metadata, responses and suggestions, click on **Filter** in the **control panel** to display the available filters. You can select multiple filters and combine them.
 
 !!! note
     Record info including metadata is visible from the ellipsis menu in the record card.
 
-=== "By metadata properties"
-
-    From the `Metadata` dropdown, type and select the property. You can set a range for integer and float properties, and select specific values for term metadata.
+From the `Metadata` dropdown, type and select the property. You can set a range for integer and float properties, and select specific values for term metadata.
 
-=== "By responses from the current user"
+!!! note
+    Note that if a metadata property was set to `visible_for_annotators=False` this metadata property will only appear in the metadata filter for users with the `admin` or `owner` role.
 
-    From the `Responses` dropdown, type and select the question. You can set a range for rating questions and select specific values for label, multi-label, and span questions.
+From the `Responses` dropdown, type and select the question. You can set a range for rating questions and select specific values for label, multi-label, and span questions.
 
-    !!! note
-        The text and ranking questions are not available for filtering.
+!!! note
+    The text and ranking questions are not available for filtering.
 
-=== "By suggestions"
 
-    From the Suggestions dropdown, Filter the suggestions by `Suggestion values`, `Score` , or `Agent` 
+From the Suggestions dropdown, filter the suggestions by `Suggestion values`, `Score` , or `Agent`. 
 
-<h4>Sort</h4>
+#### Sort
 
 You can sort your records according to one or several attributes.
 
@@ -196,4 +185,4 @@ The suggestion scores, response, and suggestion values for rating questions and
 As an `owner` or `admin`, you can edit the guidelines as much as you need from the icon settings on the header. Markdown format is enabled.
 
 !!! tip
-    If you want further guidance on good practices for guidelines during the project development, check our [blog post](https://argilla.io/blog/annotation-guidelines-practices/).
+    If you want further guidance on good practices for guidelines during the project development, check this [blog post](https://argilla.io/blog/annotation-guidelines-practices/).
