Devographics / Devographics/Monorepo
Entity/Token Management
- 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.