① Determine how to encode data structure

[tatianamac]

Per @lynncyrin 's comment in the other issue:

a. figure out how to encode the data structure into this repo, eg. yaml / json / etc file? database with a CMS? etc.

[good-idea]

Since we and other future collaborators are most likely familiar with Github and pull requests, I really like the idea of putting this all in the repo as JSON files or something similar. (Personally I don't like YAML because I always have issues with indentation that mess things up) For instance, let's say we have a directory called dictionary that looks like:

├── dictionary
│   ├── ableism.json
│   ├── ...
│   ├── minorities.json
│   ├── minoritised.json
│   └── ...

With each file adhering to a similar format, i.e.:

minorities.json

{
  "word": "minorities",
  "wordType": "noun",
  "definition": "the smaller in number of two groups constituting a whole",
  "inclusive": false,  // or perhaps avoid: true
  "issues": [
    "Minorities is not always accurate. As it deals with numbers, often the insinuation ..."
  ],
  "impact": [
"By repeatedly referring to groups as \"minorities,\" they are being infantised and made to feel minor."
  ],
  "alternatives" [
    "minoritised", // -> code would look for minoritised.json
    "__omit"
  ]
}

A technical issue could be typos breaking links between alternatives, i.e. adding minoritized (with a z). But, this could be dealt with by running a test over the entire library before any PR is made.

[coilysiren]

@good-idea do you have an idea of how you would expect the files to be edited?

[good-idea]

To get started, I'd say the quickest way to get moving is having people create forks and adding new JSON files. We could write an npm script like add-definition myNewWord that could generate a "blank" JSON file for them to edit.

The drawback here is that only people familiar with Github and pull requests could directly contribute. But, those who aren't able to could add a new "Word request" issue.

[good-idea]

Another thought here when it comes to implementing the API itself: if the "Dictionary" is standalone (as JSON files or even a database), anyone could build an API that uses it.

We could even publish the entire dictionary as its own NPM module. This could be particularly nice when it comes to supporting API requests: for instance, a Slackbot might be hitting our own API for every single message that a user types in Slack. If it is an installable module, developer (or us) could include the entire library within their code - no API requests, no servers, no latency. (Just a bigger bundle size)

[coilysiren]

quickest way to get moving ... only people familiar with Github

@good-idea leading question: have you gotten the impression that this is the type of project that should prioritize "minimizing setup time" at the cost of "minimizing the barriers to contribution"?

[tatianamac]

I think that a JSON file is fine and makes sense. I'd like though to take advantage of a CMS where we can. (Netlify CMS seems like a logical connection to me). Many contributors and writers are not necessarily familiar with Git/PRs/etc.

I'd ideally like to lower the barrier to entry and to partake while ensuring that those familiar can still use these methods if they so choose.

Re: creating their own APIs, that makes sense from a latency standpoint, but I want to be mindful of how that could be used abusively.

[good-idea]

have you gotten the impression that this is the type of project that should prioritize "minimizing setup time" at the cost of "minimizing the barriers to contribution"?

@lynncyrin I'm making no assumptions in this regard. Of course, it's a trade-off either way. I think the benefits of starting with a JSON + Github approach would be that we could get it up and moving quickly, and be more flexible if & when we make changes to the overall structure. If we decide to change the structure a bit (for instance, changing the 'avoid' flag from true/false to include an enum of values, i.e. 'avoid', 'omit', 'something-else', it would be really easy to transform all of the JSON.

If we got started with a CMS, this would be much more cumbersome. Plus, with a CMS we would either be:

• limiting user accounts and only 'admins' would be able to edit
• inviting anyone who wants to make an addition or edit

A CMS (or our own API that accepts suggestions from the website itself) makes a lot of sense once things are more figured out. In the meantime, we could make it easy for non-devs to submit suggestions through a google form (or something similar), which just adds items to a spreadsheet that devs can go through to add definitions manually.