Difference between revisions of "Folksonomy Engine/Functional use cases and specifications"

From Open Food Facts wiki
Jump to navigation Jump to search
(More questions related to private properties, etc.)
(Case 2.3 (documentation))
 
(One intermediate revision by the same user not shown)
Line 64: Line 64:
 
* The system returns:
 
* The system returns:
 
** The list of all products using this property; for each product: the product's barcode, optionally the product name, the product's photo, the last modification date, the editor of the property, the value.
 
** The list of all products using this property; for each product: the product's barcode, optionally the product name, the product's photo, the last modification date, the editor of the property, the value.
** The link to the property's documentation.
+
** The link to the property's ation.
  
 
'''Rationale''': the list of products with a particular property allows:
 
'''Rationale''': the list of products with a particular property allows:
Line 78: Line 78:
 
* The system returns:
 
* The system returns:
 
** The list of all products using this property; for each product: the product's barcode, optionally the product name, the product's photo, the last modification date, the editor of the property.
 
** The list of all products using this property; for each product: the product's barcode, optionally the product name, the product's photo, the last modification date, the editor of the property.
** The link to the property's documentation.
+
** The link to the property's ation.
  
 
'''Rationale''': this use case allows hundreds of new usages; eg. listing all the products that have been recalled last month; all products that are blue; etc.
 
'''Rationale''': this use case allows hundreds of new usages; eg. listing all the products that have been recalled last month; all products that are blue; etc.
Line 98: Line 98:
 
* The system suggests back all properties containing these letters (beginning at the second letter).
 
* The system suggests back all properties containing these letters (beginning at the second letter).
 
* The user selects a property or continues to type.
 
* The user selects a property or continues to type.
 +
* If the property is a new one, the system informs the user about social aspects of property creation: documentation, values, reuse, etc. It encourages the user to write the documentation of the new property, providing him the automatic link to the documentation.
 +
* Eventually the user documents the property (see 2.3).
 
* Back to use case 2.
 
* Back to use case 2.
  
Line 107: Line 109:
 
* The user selects a value or continues to type.
 
* The user selects a value or continues to type.
 
* Back to use case 2.
 
* Back to use case 2.
 +
 +
== 2.3 The user documents the property ==
 +
[TODO]
 +
 +
* The system shows the dedicated documentation page for the given property.
 +
* The user can specify:
 +
** usages
 +
** values
 +
** See also
 +
** the category
 +
** [to be completed]
  
 
== Questions ==
 
== Questions ==
Line 129: Line 142:
 
* Should we take care of '''stock issues''' for V1?
 
* Should we take care of '''stock issues''' for V1?
 
** Eg. I have three items of this product, one ending 2021-10-10, and two ending 2021-10-31.
 
** Eg. I have three items of this product, one ending 2021-10-10, and two ending 2021-10-31.
 +
* When a new property is created, we need to inform user about social aspects of property creation: documentation, values, reuse, etc.
 +
* Synonyms of a property.?
 
[[Category:Folksonomy Engine]]
 
[[Category:Folksonomy Engine]]

Latest revision as of 06:42, 14 October 2021

Note: to see the prototype of each functional use case, you need to install Folksonomy Engine client script.

Open Food Facts' apps and API share some common basic meta-features:

  • Links create value: every property or value or another thing that make sense should be linked to its documentation and groups it belong to.
  • All lists should be:
    • shown as table: sortable by each column; filterable; with added statistics such as number of occurrences, percentage, etc.
    • downloadable: CSV and XLSX
    • queried with a REST API
  • All product's attributes (property/value pairs) should be queried with a REST API.
  • KISS and wiki principles:
    • Straight to the point.
    • Everything can be modified (properties, values). Modified property/value pairs are not deleted, but archived and versioned.
    • Lowering the barrier: anyone should be able to do things easily.
    • Accept as many usages as we can: fields are not constrained and anyone should enter anything as a new property or a new value. Organisation will come later.
  • If possible, main lists of products should be proposed as facets, with the possibility to be mixed with other Open Food Facts facets [create a non-blocking issue]

1. The user asks the list of properties/values pairs for a given product.

  • The user selects a product (link, search result, etc.).
  • The system shows the product, with the list of property/value pairs.

Rationale: this is the main usage of Folksonomy Engine. It allows to know that a product has some particular properties which are not in the traditional Open Food Facts data model.

Questions:

  • should this use case allow to download all the property/value pairs at one time: the ones from the traditional data model, and the ones from Folksonomy Engine ?

Prototype (beta): https://world.openfoodfacts.org/product/9310036071174/paul-s-caramel-custard

2. The user enters a new property/value pair for a given product.

  • The user selects a product (link, search result, etc.).
  • The system shows the product, with a form to enter a new property/value.
  • Eventually, the user search for an existing property corresponding to his need (see dedicated use case 6).
  • The user enters the property (see dedicated functional use case 2.1).
  • The user enters the value (see dedicated functional use case 2.2).
  • The user asks the system to save the property/value pair.
  • The system checks for user authentication [this part is not detailed].
  • The system saves the property/value pair, with some metadata: the date and time of modification, the version, the username, and optionally a comment.
  • The system archives the old property/value pair and its metadata, if any.

Rationale: to discover new properties, they have to be entered by people. Open Food Facts is a project opened to any kind of editors.

Prototype (beta): https://world.openfoodfacts.org/product/9310036071174/paul-s-caramel-custard

3. The user asks for the whole list of properties.

  • The user asks for the whole list of properties: links located:
    • somewhere near the list of properties/values pairs for a given product
    • anywhere else
  • The system shows the list of all the properties with, for each property, the number of products and the number of different values.
    • It should be a list for the given context: the list corresponding to the products present in the current context, eg. Open Products Facts (create specific non-blocking issue).

Rationale: the list of all properties allows:

  • To explore the different properties and their usages.
  • To forecast the evolution of properties and their usages.
  • To observe which are the most used and the properties which are not really used.

Prototype (beta): https://world.openfoodfacts.org/keys

4. The user asks for the whole list of products with a particular property.

  • The user asks for the whole list of products with a particular property (link from the list of properties, link from a product's page using this property).
  • The system returns:
    • The list of all products using this property; for each product: the product's barcode, optionally the product name, the product's photo, the last modification date, the editor of the property, the value.
    • The link to the property's ation.

Rationale: the list of products with a particular property allows:

  • To explore all the product with a particular property.
  • To forecast the evolution of products with a particular property.
  • To observe which are the most used and the properties which are not really used.

Prototype (beta): https://world.openfoodfacts.org/key/packaging:has_character

5. The user asks for the whole list of products with a particular property/value pair.

  • The user asks for the whole list of products with a particular property/pair (link from a product's page using this property/value pair).
  • The system returns:
    • The list of all products using this property; for each product: the product's barcode, optionally the product name, the product's photo, the last modification date, the editor of the property.
    • The link to the property's ation.

Rationale: this use case allows hundreds of new usages; eg. listing all the products that have been recalled last month; all products that are blue; etc.

Prototype (beta): https://world.openfoodfacts.org/key/packaging:has_character/value/yes

6. The user searches for an existing property corresponding to his need.

  • The user asks the system for a keyword related to his need.
  • The system list all the pages of the documentation related to this keyword; this can be:
    • pages related to properties' documentation
    • pages related to a group of properties: categories, etc.

Rationale: the suggestions made by the system in the use case 2.1, based on the property name, is not sufficient to find the relevant properties; eg. thehas_character property is namely dealing with cartoon characters: searching for cartoon won't help to find this property. Folksonomy Engine needs efficient tools to allow users reuse existing properties and not always reinvent the wheel.

2.1. The user enters a property for a given product.

  • The user starts typing the name of a property.
  • The system suggests back all properties containing these letters (beginning at the second letter).
  • The user selects a property or continues to type.
  • If the property is a new one, the system informs the user about social aspects of property creation: documentation, values, reuse, etc. It encourages the user to write the documentation of the new property, providing him the automatic link to the documentation.
  • Eventually the user documents the property (see 2.3).
  • Back to use case 2.

2.2 The user enters the value.

  • If possible, the system suggests some values based on the current values already given for the property.
  • The user starts typing the content of the value.
  • The system suggests back all current values related to this property and containing these letters (beginning at the second letter).
  • The user selects a value or continues to type.
  • Back to use case 2.

2.3 The user documents the property

[TODO]

  • The system shows the dedicated documentation page for the given property.
  • The user can specify:
    • usages
    • values
    • See also
    • the category
    • [to be completed]

Questions

  • For transparency reasons (and maybe for other reasons):
    • Should we provide a use case to let the user see the history of property/value pairs for each product? Version 2?
    • Should we provide a use case to let the users see the history of all property/value pairs for all product (something like the "recent changes" in Mediawiki/Wikipedia)? Version 2?
  • Should we immediately provide use cases related to private property/value pairs for V1?
    • Eg. my_morning_diet=yes;
    • Should these use cases take care of stocks issues?
    • Could public properties be used privately?
      • CONs: one can build a big private database with Open Food Facts resources.
    • Could private properties be used publically?
    • If private properties can only be used privately, should we clearly separate them from the private ones:
      • Show another section in the product page?
      • Name them to ensure they are private; eg. private:my_prefered_product=yes
    • Should private properties be documented as well as public properties?
    • Should some properties be necessarily private? Eg. our_prefered_product=yes
    • Should the property suggestion take care of private properties?
    • Should we adopt some limits to private usage? (to take care of common resources)
      • How would it look like? Max number of property/value pairs?
  • Should we take care of stock issues for V1?
    • Eg. I have three items of this product, one ending 2021-10-10, and two ending 2021-10-31.
  • When a new property is created, we need to inform user about social aspects of property creation: documentation, values, reuse, etc.
  • Synonyms of a property.?