Keys discussions, description and documentation #16

[to be completed]

For the moment, keys are self-described by their name. Eg. Color_Of_The_Cap.

But in a folksonomy, users have to build some consensus of the meaning of each tag.

We need 3 different kind of usages:

• discussions: a solution to discuss each property (structured discussion, not just chatting)
• description: because the name can be ambiguous or not self-described, we need to provide a short description in context (eg. when a user is searching for a property while modifying a product)
• documentation: the majority of the properties would benefit to have a complete documentation: description, rationale, examples, allowed values, main values, etc.

In OpenStreetMap community, for example, their wiki is used to describe all the tags (features) of the map (see Map Features). Every key is having its own page, eg. aerialway, and the "discussion" tab host discussions about it (eg. discussions about the aerialway tag).

Option 1: OFF wiki only

Open Food Facts wiki can host description, documentation, and even discussions related to each property (thanks to the "discussion" tab). I created a wiki page describing some Folksonomy Engine use cases.

Pros:

• all contents grouped in a unique and already existing tool (no other tool to maintain)
• allows rich documentation (rich styling, photos, etc.)
• it's now easy to write on the wiki thanks to the visual editor (no more wiki syntax to learn)
• documentation can be easily translated in different languages
• documentation can be queried by Mediawiki API (eg. some tool can extract the first paragraph of each page)
• it's possible to create predictable links, eg. https://wiki.openfoodfacts.org/Folksonomy/Property:Color_Of_The_Cap

Cons:

• wikipedians and OpenStreetMap contributors use to discuss inside their wikis, but it's not very easy to use and read (example)

Option 2: API + wiki (+ discussion tool?)

• description: API
• documentation: wiki
• discussions: wiki or discussions tool

Pros:

• all pros belonging to wiki usage: rich documentation, etc.
• description in API allow UI integration

Cons:

• need to enhance the API (with i18n in mind)
• need to provide a UI to enter/modify new descriptions

Option 3: API + discussion tool

• description: API
• documentation: API
• discussions: discussion tool