Clarify tag usage for resources

[ryanatkn]

As we start getting more resource submissions, we'll want a clear set of guidelines for tagging resources so they remain useful. Too much or too little looseness can make tags difficult or unhelpful in practice. Curating them well means every resource that should be under a tag is, and the tags are specific, descriptive, and manageable in number. Here on GitHub we have the topics svelte, sveltejs, svelte-v3, svelte3, and many un-topic'd projects, which is just a leaky unhappy experience.

The search function already does fuzzy matching against the name, description, url, and other fields, leading me to believe we can be tighter with our tag usage.

As a concrete example, here's our first submission that prompted me to post this: https://github.com/sveltejs/community/pull/21/commits/db01c41fbf514cabff8551372e260533a31251f1

  - name: "`Real World Svelte and Google Cloud Masterclass`"
    url: "https://www.youtube.com/playlist?list=PLCrwuqjmVebK08Cwz_XB55cNKFfFYOMGo"
    description: A video series taking you through the Real World Svelte app tied in with a Google Cloud Functions backend
    tags:
      - Sapper
      - Real World
      - Google Cloud

I'm currently thinking I'd tag this resource with sapper, videos, and maybe learning or education, and I'd remove Real World and Google Cloud, which can be searched.

@kevmodrome brought up the idea of having hierarchical categories. The original resources list was organized that way, and it works well but is unable to express cross-cutting information like labeling official resources unless they can belong to many categories. Does it make sense to have both nestable categories and tags as distinct systems? Or should we try to make it one system? Should we rethink cramming code libraries and arbitrary links into the same resource system?

The initial set of tags for the community resources came by copying over the headings from awesome-svelte-resources, so consider them a first pass.

[swyxio]

i think many hierarchical category vs cross cutting tag attempts kinda fail bc its never clear from the outset which is which... and you end up having some tags correlate 1:1 with categories (and therefore are useless double work) or just straight up get mislabeled. the CMS can help with that, if we want to go down that path.

i like the idea of manually grooming the hierarchy, aka the hierarchy doesnt exist anywhere except in the presentation layer, and is something we fix manually instead of generate from data. this way, everything can just exist as tags at the data layer.

i also like the idea of splitting reusable libraries and other resources (which may include templates!). maybe this goes into the "recipes" section and we rename the "recipes" section to something else?

[ryanatkn]

For reference here's the initial tag hierarchy: (it's far from perfect - for example "routers" should be under "components and libraries")

categories:
  - official links
  - communities
  - integrations
  - web app frameworks
  - templates
  - testing
  - routers
  - components and libraries
  - native
  - experiments
  - example app showcase
  - media
  - other lists and resources
# including sub-categories
official links:
  - language translations
communities:
  - Telegram chat rooms
integrations:
  - bundler plugins
  - preprocessors
  - cli tools
  - editor tools
web app frameworks:
templates:
  - electron templates
  - mobile templates
testing:
routers:
  - Svelte-specific routing
  - generic routing
components and libraries:
  - ui component sets
  - web component sets
  - layout and structure
  - inputs and widgets
  - fonts and icons
  - forms and validation
  - images
  - charts
  - time and date
  - notifications
  - maps
  - internationalization
  - stores and state
  - interaction
  - async loading
  - social and other 3rd party services
  - development and documentation
  - other components and libraries
native:
experiments:
example app showcase:
media:
  - talks
  - podcasts and other videos
other lists and resources:

[kevmodrome]

All right, so I've made some kind of mockup, not 100% satisfied - Ideally I would like to put some link to NPM and get the last_updated attribute in somewhere.

https://www.figma.com/file/mow5dQ25GbML8YhapGXlsv/Svelte-Community?node-id=4%3A3

[kevmodrome]

Btw, I quite like the current color scheme, combining the two (design and current scheme) would look very dope.

[swyxio]

@kevmodrome nice! i think this is good enough for our libraries section.

for the non code libraries section (which includes boilerplates, templates, and non code resources) what happens if you vary the description lengths (sometimes have no descriptions) and what happens if it is not a gh resource? what happens if there is a very long name? lets plan for that too.

also lets have a nice call to action if we have an empty state, like... "no resources found for {searchterm}! add one here!" maybe use one of those svg placeholder things from undraw

[kevmodrome]

Good idea! Will keep exploring variants.

[ryanatkn]

re: what @sw-yx said, I like the ideas of maintaining a manual hierarchy and keeping the tags and categories unified. Resources could have their tag hierarchy filled out in the transform step, simplifying the data definition to require only the deepest tag(s).

Thinking out loud here - what if resources have a type:

• template - the most important resource-type-specific information here is what dependencies it has - this could be structured in the UI (like tags but specifically deps) and possibly automated by scraping the package.json
• recipe - should probably point to a template repo, but enhanced with documentation rendered on the website (arguably, recipes are combined with templates and the docs are simply rendered readmes), and perhaps recipes have a hand-crafted index instead of search/filter functionality
• library/repo (or a better name? confusing with templates) - hierarchical categories/tags, has npm link/stats if appropriate
• links - blog posts, videos, social media, etc

Where do non-library, non-templates fit in, like bundler and editor plugins? Alongside libraries? Maybe templates are the only specially handled code resources?

Do users want/expect to see templates and libraries interleaved in their searches? Maybe sometimes, if toggled on? You could imagine templates displayed with enhanced information (like their deps list) and still appear alongside libraries. Keeping them separate seems ok too.

[swyxio]

numbering my comments so it might be easier to reference:

1. i think this listing of types is good and simplifying the top level hierarchy to just 4ish types is a good idea.
2. i'm wary of ruining things by having scope grow too quickly and unmaintainably. so lets keep that in mind as we explore. we can trust users to click links and figure stuff out for themselves off-site. so if we're ever in doubt, lets opt to do less. still some things (like crawling number of stars and downloads) are definitely nice to have.
3. i actually wonder if we should not give templates special treatment. templates tend to get bloated and out of date and encourage people to suspend critical judgment, because they encourage adding hay to the haystack. instead, opinionated reusable toolkits like baelte and ssg might be something we should encourage. of course, svelte mostly operates on getting people to clone templates right now, so i dont know how strongly i hold this view tbh.
4. i like interleaving results and basically as far as possible leaving things on one page. this is inline with how svelte and sapper both have greppable docs. frankly we're somewhat going the extra mile with the fuzzy filter.

[ryanatkn]

I agree on all points. Starting simple is safe and we could do more in the future with templates/etc without data changes using the tag hierarchy model, I think. I'll find some time soon to propose a simple tag hierarchy that includes all of the existing stuff.

[kevmodrome]

This sounds good.

[ryanatkn]

I'm struggling to find a scheme that I like here, even after a couple weeks of vacation. Does anyone have opinions or a holistic proposal to share? I imagine we'll have more opinions with time and experience using it.

I'm hesitating on the idea of having a small number of super generic top-level tags because of the added noise and limited usefulness, but that may be fixable in the UI.

Here are some possible incremental changes to what's already there:

• consolidate code resources
  • move routers under components and libraries
  • remove the generic routing tag and items (if it has no integration with Svelte, it probably doesn't belong)
  • move the integrations child tags to components and libraries, removing integrations
  • move testing under components and libraries
  • consider moving experiments and native under components and libraries
• shorten and nest some tags
  • components and libraries -> libraries
  • web app frameworks -> frameworks
  • other components and libraries -> misc, or remove this tag completely and categorize the items if possible
  • example app showcase -> showcase, or move it out of resources to its own section of the website
  • Telegram chat rooms -> Telegram
  • other lists and resources -> split into newsletters, aggregators, ??, and move them under media or remove the top-level media tag
  • podcasts and other videos -> split into podcasts and videos (a resource can be a talk+video, podcast+video, etc)
  • social and other 3rd party services -> 3rd party services
  • some more could be shortened but I'll stop there for now
• add some tags
  • sapper, which gets applied to many items in libraries and templates
  • recipes (unless they have their own distinct section on the website)
  • learning or education
  • blogs under media (what about tutorial? is that just blog+learning?)

These changes bring us to this:

- communities
  - Telegram
- frameworks
- templates
  - electron
  - mobile
- libraries
  - testing
  - bundler plugins
  - preprocessors
  - cli tools
  - editor tools
  - routers
  - ui component sets
  - web component sets
  - layout and structure
  - inputs and widgets
  - fonts and icons
  - forms and validation
  - images
  - charts
  - time and date
  - notifications
  - maps
  - internationalization
  - stores and state
  - interaction
  - async loading
  - social and other 3rd party services
  - development and documentation
- native
- experiments
- showcase
- media
  - talks
  - videos
  - podcasts
  - newsletters
  - aggregators
  - blogs
- language translations
- sapper
- learning

[kevmodrome]

I think we can do with a few more pages to lessen the number of tags.

Overall structure of site:

• Community Page (events, meetups, etc)
• Showcase (links to pages built using Svelte, much like the Gatsby showcase page)
• Packages, Libs and Components (like the resources page but only for actual code)
• Resources (learning, media, etc.)
• Recipes (cookbook style/list of good REPLs)

The last three would be the "old" resource page but split up basically, combined with the recipes page that is still a todo.

In my opinion it's pretty rare to be searching for packages at the same time learning resources. Separating them would clear up a lot of the bloat. This way we can also be a bit more granular when it comes to the tags (I still think we should stick to a few, maybe 10 or so for each page).

[ryanatkn]

I like that a lot, and those categories look pretty clear and complete to me.

[swyxio]

ok. i'll try to work on this over the weekend. love the collaboration! thanks for helping to think this through 🙇‍♂️

[swyxio]

I have gone thru the rearchitecture exercise in https://github.com/sveltejs/community/pull/30 - had to make some calls where things didn't really fit Kev's proposal, but the rough idea is there. feedback welcome. once we merge this rearchitecture we can work on the tag hierarchy and then also fill out the showcase and recipes (which is probably more important)

[ryanatkn]

Because we've made a lot of progress on this and now much is outdated, I think future changes should go through a new issue.