openfoodfacts/folksonomy_api

Keys discussions, description and documentation

CharlesNepote opened this issue · 3 comments

CharlesNepote commented

[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
VaiTon commented

What about GitHub Discussions? Or even a new repo, like what Matrix does.

CharlesNepote commented

Thanks for your feedback @VaiTon. Github Discussions is interesting but it also has some drawbacks.

Pros:

  • nice and clean UI (maybe a bit too much information/distractions)
  • some interesting features (upvoting, categories, labels, "Most helpful" (really nice), ...)
  • nice for developers (often already registered to Github, familiar UI, a step aside code and issues, etc.)

Cons:

  • nice for developers only? Who knows Github? Who uses Github?
  • Discussions are lost aside many other features (weird things for non-tech people: code, issues, Pull requests, actions, security, etc. Per comparison, a forum solution can be a single website where people are not disturbed or intimidated by weird tabs/menus.
  • Discussions are only possible per repository (there's a discussion related to it)
  • data portability and sustainability? While it's easy to move git repositories to other services, it's probably not the same for discussions.

In my opinion, Github Discussions are nice for pure tech projects, but I'm not comfortable with it for a project as we are with many non-tech people. I think we should really try to be more inclusive with non-tech people.

  • 👍1