2020-10-31: Some glossary terms are overloaded terms (have other meanings in this context) about glosario

[baileythegreen]

Is the model for the term graph what should be done?

 - slug: graph
  ref:
    - tree
  en:
    term: "graph"
    def: >
      1. A plot or a chart that displays data, or 2. a data structure in which
      [nodes](#node) are connected to one another by [edges](#edge).

[fmichonneau]

Thanks for bringing this up.

I think the format should be:

  en:
    term: "graph"
    def: >
      1. A plot or a chart that displays data.

      2. A data structure in which [nodes](#node) are connected to one
         another by [edges](#edge).

so we'll get a numbered list which would be more semantically correct and improve acceesibility.

[baileythegreen]

👍 I am happy to work on that (particularly as I have actually read through the entire glossary, which I imagine is rare). And I have a list I started of terms that are overloaded.

I would note though, that after going through the full thing, it seems like there is a different way some people have done this. Looking at the various feature_* entries, for example, you have:

- slug: feature_branch
  ref:
    - master_branch
  en:
    term: "feature branch"
    def: >
      A [branch](#branch) within a [Git](#git) [repository](#repository)
      containing [commits](#commit) dedicated to a specific feature, e.g., a
      [bug](#bug) fix or a new function. This branch can be merged into another branch.


- slug: feature_data
  en:
    term: "feature (in data)"
    def: >
      A variable or observable in a dataset.


- slug: feature_engineering
  en:
    term: "feature engineering"
    def: >
      The process of choosing the variables to be used as inputs to a [model](#model).
      Choosing good features often depends on [domain knowledge](#domain_knowledge).


- slug: feature_request
  en:
    term: "feature request"
    def: >
      A request to the maintainers or developers of a software program to add a
      specific functionality (a feature) to that program.


- slug: feature_software
  en:
    term: "feature (in software)"
    def: >
      Some aspect of software that was deliberately designed or built. A [bug](#bug)
      is an undesired feature.

I noticed this after creating this issue, but I think this method:

1. is confusing (because it is not immediately clear that these (some of these) define the term feature in different contexts (feature_branch, feature_engineering, and feature_request are actually terms, not a term + context));
2. makes it harder to know where internal links should point (particularly if two entries are somewhat-similar; and
3. does not reflect how actual dictionaries are written. The numbering method you propose is ore in-line with the standard.

I think the numbering system, with a way to specify context (see example image of different definitions of run, *noun*) is the way to go, but I imagine implementing this requires adding to the YAML parsing code used. (I haven't looked at this, yet, so don't even know what language it's written in.)