9
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − FILL ME+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
this is a first version for taxonomy editor documentation
Welcome to the Taxonomy Editor documentation.
This editor is a tool designed to make editing taxonomies easy for everyone.
== But first, what is a taxonomy ? ==
Taxonomies are at the heart of Openfoodfacts in various aspects :
* They facilitate the identification of components such as ingredients, labels, brands, …
* They establish connections between these components and their relevant properties
* They enable the calculation of useful metrics such as nutri-score, eco-score, and allergen identification, …
Technically, a taxonomy is represented as a DAG (directed acyclic graph) where each leaf node has at least one parent.
== Why is this editor important ? ==
Currently the taxonomies are stored in raw text files in our [https://wiki.openfoodfacts.org//github.com/openfoodfacts/openfoodfacts-server/tree/main/taxonomies repository].
As you can imagine, contributing to improving taxonomies requires significant effort and understanding. Moreover, manual editing can easily result in inconsistencies between taxonomies and even errors within a single taxonomy due to the lack of a format checker.
This is where the Taxonomy Editor comes in: it aims to help the contribution process for improving taxonomies and enhance overall quality.
== How you can contribute ? ==
First you arrive at the home page where you have two options :
* create a new project for taxonomy editing : Start with a currently used taxonomy of your choice and begin editing.
* open an existing project for taxonomy editing : Collaborate with others on editing a taxonomy together.
[[File:ImageHomePage.png|thumb]]
=== Collaborate with others ===
To join an existing project, simply click on "OPEN EXISTING PROJECT" from the home page. You will then be directed to the existing projects page.
Here, you'll find a list of projects that contributors have already initiated. Each project includes information such as the taxonomy being edited and a description outlining its goals, ensuring clarity for potential contributors. The status indicates the progress of the project:
* '''''OPEN''''': The project has been created, but no changes have been exported to Github yet
* '''''EXPORTED''''': Changes have been exported to Github, but contributions are still welcome, and you can export your modifications
* '''''CLOSED''''': The project has been exported, and further contributions are not required
While additional information such as the Github branch name and error count encountered by the parser are provided in the table, they are not essential for contributing.
To contribute to a project, simply click on the pencil icon!
=== Edit the taxonomy ===
First you arrive on a page listing all the root nodes, which are nodes without parents.
you can choose one of them by clicking on the pencil button or add a root node by clinking on the + button, where you will have to choose a main language and a name for the node.
=== Edit a node ===
Once you've selected the node you wish to edit, you'll be directed to the edit page.
Here, you'll find the parent nodes and children of the selected node. You can easily add a child node to expand the taxonomy structure and navigate through nodes by clicking on their parent or child nodes.
Next, you'll encounter the translations for the node. The primary language of the node and any "universal" translations (if they exist) are automatically displayed. To add or check translations for a specific language, simply click on "n LANGUAGES SHOWN" and select the desired languages. If "All languages" is not visible and you wish to add a universal translation, simply check the corresponding checkbox.
For each language, you can add a translation by clicking in the designated area. You can also adjust the order of translations within a section, allowing you to rearrange them as needed, even setting a new first translation.
Finally, you'll find a list of properties associated with the node. Here, you can edit existing properties, add new ones, or remove unnecessary ones. Property names must be unique and adhere to the format "name:of:the:property:lc" (where "lc" represents the language code). These names should contain only letters and numbers, excluding special characters.
Once you've completed editing the node, remember to save your changes by clicking the blue button; otherwise you would loose your modifications.
=== Make your contribution ===
Navigate to the export tab in the header bar to export your edited taxonomy.
From there, you have the option to download the file locally or create a pull request (PR), either initiating a new one or adding a commit to an existing PR, ensuring that your modifications are visible on GitHub!
Upon submission, your PR will undergo review, and upon approval, it will be merged. Through this process, you'll have contributed to improving the quality of the taxonomy.