Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

① Determine how to encode data structure #6

Open
tatianamac opened this issue Oct 21, 2019 · 7 comments
Open

① Determine how to encode data structure #6

tatianamac opened this issue Oct 21, 2019 · 7 comments

Comments

@tatianamac
Copy link
Collaborator

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
Copy link

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
Copy link

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

@good-idea
Copy link

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
Copy link

good-idea commented Oct 21, 2019

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
Copy link

coilysiren commented Oct 21, 2019

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
Copy link
Collaborator Author

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
Copy link

good-idea commented Oct 21, 2019

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.

@tatianamac tatianamac transferred this issue from selfdefined/web-app Aug 29, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants