Devographics / Devographics/Monorepo

Entity/Token Management

Open
#533 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
178
Forks
55
Avg merge
1m
Merged PRs (30d)
2

Description

A few notes.

### General Notes

1. Entities/tokens can include English content (name, description, etc.). Corresponding translations for other languages can be stored in the locale's respective repo.
2. Pain points related to a specific API, feature, library, etc. should *not* use their own token. Instead, we should use the canonical entity for that item to ensure all extra metadata can be displayed to the user. Bad: `css_grid_issues`. Good: `css_grid`.
3. We should avoid entities/tokens with duplicate `id`s as much as possible. Even though we can merge multiple definitions, it does make everything much harder to reason about compared to having a single canonical definition.

### Descriptions

1. Entities can have a general `description` field and a specialized `descriptionIssues` field that is specifically about when that entity is mentioned in the context of a pain point (an example `descriptionIssues` field for `css_grid` could be `Issues about CSS Grid layouts`).
2. For pain point tokens, that issues description can be assigned to the regular `description` field since those tokens are always used in a pain point question context.

### Token IDs

1. When defining new codes, make their `id` as explicit as possible to avoid ambiguity or name collisions, especially when it comes to common nouns or words. Bad: `workplace`. Good: `workplace_issues` (there could be a JS library called "workplace.js" with the id `workplace` already).
2. Avoid tokens with really broad or vague definitions, like `interactivity`. They will be applied to too many answers. On the other hand, concrete tokens such as `styling_and_customization` are fine even if they too get applied to a lot of answers.

### Nesting

1. Avoid tokens that only have a single child. Bad: `apis > haptic_feedback > vibration_api`. Good: `apis > vibration_api`.
2. Do not set tokens such as `parentId: css_properties` or `parentId: css_issues` manually on tokens. Grouping everything under a single `CSS Issues` parent bucket would not make for a good chart, and moreover these kind of tokens can be extracted from existing token tags. See "future questions" below.

### Future Questions

1. Should we support entities/tokens having more than one possible parent? We could then assign 2-3 parents, and the nesting would happen based on whatever parent bucket is actually present in the chart's dataset.
2. We should also have a system to automatically set parents based on token tags. For example, if a token is tagged with `css_features` and a dataset has a `css_features` bucket, it would make sense to auto-nest that token under that bucket.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.