docs(#1445): introduce basics (#1537)

* basics tutorial file * changes applied * preliminar version of basics and annotations * basics and annotation * first version * images folder * new videos and text * more updates * add dedicated validate predictions section * add basics to index * add how to annotate data section * remove/refactor media * How to upload data remake * add missing screenshots * remove bold link to fix missing spaces * fix admonitions * Correct dataset name, align with screenshot Co-authored-by: leireropl <leireropl10@gmail.com> (cherry picked from commit 56ae851)
argilla-io · Jun 7, 2022 · 88b20bd · 88b20bd
1 parent 7d7b876
commit 88b20bd
Show file tree

Hide file tree

Showing 8 changed files with 977 additions and 23 deletions.
diff --git a/docs/_static/getting_started/basics/coffee_reviews.png b/docs/_static/getting_started/basics/coffee_reviews.png
diff --git a/docs/_static/getting_started/basics/ecdc_phrases.png b/docs/_static/getting_started/basics/ecdc_phrases.png
diff --git a/docs/_static/getting_started/basics/first_record.png b/docs/_static/getting_started/basics/first_record.png
diff --git a/docs/_static/getting_started/basics/manual_annotations.png b/docs/_static/getting_started/basics/manual_annotations.png
diff --git a/docs/_static/getting_started/basics/snapchat_reviews.png b/docs/_static/getting_started/basics/snapchat_reviews.png
diff --git a/docs/getting_started/basics.ipynb b/docs/getting_started/basics.ipynb
diff --git a/docs/index.rst b/docs/index.rst
@@ -164,6 +164,7 @@ You can join the conversation on our Github page and our Github forum.
 
    getting_started/setup&installation
    getting_started/concepts
+   getting_started/basics
    getting_started/user-management
    getting_started/advanced_setup_guides
 

diff --git a/docs/reference/webapp/annotate_records.md b/docs/reference/webapp/annotate_records.md
@@ -7,34 +7,24 @@ Rubrix's powerful search and filter functionalities, together with potential mod
 
 You can access the _Annotate mode_ via the sidebar of the [Dataset page](dataset.md).
 
-## Search and filter
-
-![Search and filter for annotation view](../../_static/reference/webapp/filters_all.png)
-
-The powerful search bar allows you to do simple, quick searches, as well as complex queries that take full advantage of Rubrix's [data models](../python/python_client.rst#module-rubrix.client.models).
-In addition, the _filters_ provide you a quick and intuitive way to filter and sort your records with respect to various parameters, including the metadata of your records.
-For example, you can use the **Status filter** to hide already annotated records (_Status: Default_), or to only show annotated records when revising previous annotations (_Status: Validated_).
+## Create labels
 
-You can find more information about how to use the search bar and the filters in our detailed [search guide](search_records.md) and [filter guide](filter_records.md).
+![Create new label](../../_static/reference/webapp/create_newlabel.png)
 
-```{note}
-Not all filters are available for all [tasks](../../guides/task_examples.ipynb).
-```
+For the text and token classification tasks, you can create new labels within the _Annotate mode_.
+On the right side of the bulk validation bar, you will find a _"+ Create new label"_ button that lets you add new labels to your dataset.
 
 ## Annotate
 
 To annotate the records, the Rubrix web app provides a simple and intuitive interface that tries to follow the same interaction pattern as in the [Explore mode](explore_records.md).
-As the _Explore mode_, the record cards in the _Annotate mode_ are also customized depending on the [task](../../guides/task_examples.ipynb) of the dataset.
+As in the _Explore mode_, the record cards in the _Annotate mode_ are also customized depending on the [task](../../guides/task_examples.ipynb) of the dataset.
 
 ### Text Classification
 
 ![Multilabel card, validated](../../_static/reference/webapp/textclassification_multilabel.png)
 
 When switching in the _Annotate mode_ for a text classification dataset, the labels in the record cards become clickable and you can annotate the records by simply clicking on them.
-You can also validate the predictions shown in a slightly darker tone by pressing the _Validate_ button:
-
-- for a **single label** classification task, this will be the prediction with the highest percentage
-- for a **multi label** classification task, this will be the predictions with a percentage above 50%
+For multi-label classification tasks, you can also annotate a record with no labels by either validating an empty selection or deselecting all labels.
 
 Once a record is annotated, it will be marked as _Validated_ in the upper right corner of the record card.
 
@@ -47,15 +37,13 @@ Under the hood, the highlighting takes advantage of the `tokens` information in
 You can also remove annotations by hovering over the highlights and pressing the _X_ button.
 
 After modifying a record, either by adding or removing annotations, its status will change to _Pending_ and a _Save_ button will appear.
-You can also validate the predictions (or the absent of them) by pressing the _Validate_ button.
-Once the record is saved or validated, its status will change to _Validated_.
+Once a record is saved, its status will change to _Validated_.
 
 ### Text2Text
 
 ![Text2Text View](../../_static/reference/webapp/text2text_annotation.png)
 
 For text2text datasets, you have a text box available, in which you can draft or edit an annotation.
-You can also validate or edit a prediction, by first clicking on the _view predictions_ button, and then the _Edit_ or _Validate_ button.
 After editing or drafting your annotation, don't forget to save your changes.
 
 ## Bulk annotate
@@ -68,12 +56,44 @@ Then you can either _Validate_ or _Discard_ the selected records.
 
 For the text classification task, you can additionally **bulk annotate** the selected records with a specific label, by simply selecting the label from the _"Annotate as ..."_ list.
 
-## Create labels
+## Validate predictions
 
-![Create new label](../../_static/reference/webapp/create_newlabel.png)
+In Rubrix you can pre-annotate your data by including model predictions in your records.
+Assuming that the model works reasonably well on your dataset, you can filter for records with high prediction scores, and simply _validate_ their predictions to quickly annotate records.
 
-For the text and token classification tasks, you can create new labels within the _Annotate mode_.
-On the right side of the bulk validation bar, you will find a _"+ Create new label"_ button that lets you add new labels to your dataset.
+### Text Classification
+
+For this task, model predictions are shown as percentages in the label tags.
+You can validate the predictions shown in a slightly darker tone by pressing the _Validate_ button:
+
+- for a **single label** classification task, this will be the prediction with the highest percentage
+- for a **multi label** classification task, this will be the predictions with a percentage above 50%
+
+### Token Classification
+
+For this task, predictions are shown as underlines.
+You can also validate the predictions (or the absence of them) by pressing the _Validate_ button.
+
+Once the record is saved or validated, its status will change to _Validated_.
+
+### Text2Text
+
+You can validate or edit a prediction, by first clicking on the _view predictions_ button, and then the _Edit_ or _Validate_ button.
+After editing or drafting your annotation, don't forget to save your changes.
+
+## Search and filter
+
+![Search and filter for annotation view](../../_static/reference/webapp/filters_all.png)
+
+The powerful search bar allows you to do simple, quick searches, as well as complex queries that take full advantage of Rubrix's [data models](../python/python_client.rst#module-rubrix.client.models).
+In addition, the _filters_ provide you a quick and intuitive way to filter and sort your records with respect to various parameters, including the metadata of your records.
+For example, you can use the **Status filter** to hide already annotated records (_Status: Default_), or to only show annotated records when revising previous annotations (_Status: Validated_).
+
+You can find more information about how to use the search bar and the filters in our detailed [search guide](search_records.md) and [filter guide](filter_records.md).
+
+```{note}
+Not all filters are available for all [tasks](../../guides/task_examples.ipynb).
+```
 
 ## Progress metric