RFC: fight for simplicity with regards to Open Web Components project future

RFC: Buildless.md

Goal

1. Help the adoption of Going Buildless by frontend developers, regardless of frameworks or libraries they use.

2. Make the most valuable tools related to Going Buildless easy to discover, use and contribute to.

Overview

@open-wc has become an umbrella project which consists of lots of parts mixed in the same repo and docs site:

• tools:

  • es-dev-server
  • karma-esm
  • @mdjs/core
  • storybook-prebuilt (separate repo)
  • mdjs-viewer (separate repo)

• utilities:

  • building-utils
  • polyfills-loader
  • import-maps-generate
  • import-maps-resolve

• plugins:

  • rollup-plugin-html
  • rollup-plugin-polyfills-loader
  • storybook-addon-web-components-knob
  • storybook-addon-markdown-docs
  • webpack-index-html-plugin

• presets:

  • building-rollup
  • building-webpack

• testing helpers:

  • chai-a11y-axe
  • semantic-dom-diff
  • testing-helpers

• WC helpers:

  • dedupe-mixin
  • lit-helpers

• configs:

  • eslint-config
  • prettier-config
  • testing-karma-bs
  • testing-karma
  • testing

• recommendations:

  • testing-wallaby
  • deploying
  • IDE (VSCode)

• onboarding:

  • create
  • codelabs

• experiments:

  • scoped-elements

Problems

IMHO, the current situation has the following problems, that affect developer experience:

• navigation. I always struggle to find a link to ES dev server docs, due to complex navigation structure. And I'm already an experienced user familiar with the site. What about newbies who just discovered open-wc?

• piling up content. Things like ESLint, Prettier, VSCode or Wallaby are definitely useful for those who never tried them. However, these are also matter of personal preference and probably should be downplayed.

• contributing. The monorepo itself is kinda scary for certain users. It might be easier to maintain, but less clear how to contribute - find an issue, setup the environment locally, submit a PR, deal with CI.

• versioning. Because of Lerna, there are many releases that are version bumps only. That forces me as a user to look through CHANGELOG entries figuring out if there are valid reasons for me to upgrade.

• branding. The joke about WC has been so much repeatedly happening, and honestly now it's too annoying. When you reach out to external developers, their first impression really matters, and now it's a bit weird.

• positioning. Many tools are not specific to web components, and could be used by frameworks users. Unfortunately, there is a somewhat negative feeling about Web Components in certain communitites.

• walled garden. Despite the fact that developing with ES modules is becoming popular (e.g. Snowpack), the tools and libraries by open-wc are mostly used by web components (former Polymer) community.

Proposal

Let me make a suggestion that might tackle some of the problems and help to achieve goals:

• introduce Buildless as a separate brand and GitHub org.

• suggested slogans:

  • "build less, do more"
  • "start with index.html"
  • "you might not need build tools"
  • "forget about JS fatigue"

• move the following packages to separate repos under new org:

  • tools
  • utilities
  • plugins (except storybook-addon-web-components-knob)
  • presets

• create a new website (consider 11ty). These domains are free:

  • https://buildless.dev
  • https://buildless.org

• keep configs, recommendations, codelabs, WC helpers under Open WC

• refer to Buildless as a "sibling" project from https://open-wc.org

• invite other tools authors (Vue.js / Vite, Snowpack) to collaborate

Thoughts?

I definitely agree that the docs have become somewhat of a beast, and I agree that we can benefit from a separation.

• navigation
  This is very much true, and a separation of content would go a long way here.

• piling up content
  Also true, we'll need to overhaul the docs and filter out outdated or non-essential content.

• contributing & versioning
  I understand the point here, but its also more of a javascript/publishing problem I guess? I do agree we can be more helpful to new contributors. Im not sure if this was actually implemented, but we already had some discussions about commitlint for example.

• branding
  I do agree with this (although I also think the JS community could grow up a little bit 🤷‍♂️), but I'm very much not in favor of renaming open-wc. I think it would be very unfortunate to change the name at a point in time where we've build up quite a following/name recognition

Proposal:

• Buildless
  Im somewhat hesitant of naming it 'Buildless'. While I subscribe to the ideology of going buildless, many 'buildless' tools are very much not buildless, and I just think we're "not quite there" yet. Also I think at this point in time its somewhat of a 'hype' name, I'm not sure how relevant the term 'buildless' will be in a few years from now. (However, I do like the "build less, do more" catch phrase)

• New site
  @Westbrook has been doing some explorations of 11ty, and we've already been looking at migrating the docs to 11ty.

Overall I think a good first step here could be to filter outdated content from open-wc, make a separation of what should be open-wc content or not, and move stuff to a separate (to be named) site.

Imo open-wc should be all about getting started with web components, and making it easy for people to build web components or apps with web components. This includes guides/codelabs/examples, but also build/test/lint etc configurations. We've also discussed giving more advanced/in-depth guidance on building apps.

The 'sister' site could then be for the more tooling kind of stuff.

plugins (except storybook-addon-web-components-knob)

If we move the tooling to a separate site, we should also move web component related tooling to that site.

I can't be more agree, thanks @web-padawan!

If my experience helps:

• I use OWC for getting started with almost anything, and also refer others here in Austin who are otherwise weirded out that the world isn't still fixated on their own React or Angular or even JQuery worlds from 2016 or 2013 or before. OWC establishes credibility for a look at shifting to WC, ESM et al.

• It's a challenge for me to "sort out" the vectors I am interested in. Example: we don't do buildless AT ALL, but we still use all the rollup help we can get from OWC, which is considerable. Too many other examples to cite here.

• OWC's guides - especially having them centrally referenced from a credible site - are super critical to many new experimenters at many junctures.

If there is one weakness to the OWC committers it is being too contextually immersed. Which is weird because this group does more to bridge to those who have zero context than anyone else I am aware of. Anything you can do to keep from distancing yourself unintentionally via TMI is probably a good thing. Note I am not prescribing how :(

If there is one weakness to the OWC committers it is being too contextually immersed.

Could you elaborate on what you mean with this exactly? How could we improve on this?

Could you elaborate on what you mean with this exactly? How could we improve on this? re: contextually immersed.

OK, funny story should do the trick.

I have to work constantly at not over-explaining things to the point of getting eye rolls - just a personal problem - and being elderly doesn't help. So I put together a 5 minute video on how to do something - instead of a 30 minute - to compensate for over-explaining. It was good enough. Who would watch a 30 minute video? Nobody, for this.

So my boss goes over it and then begins to rake me over the coals because I didn't tell him about how to use nvm when he had the wrong version of node to run the process. So now Mr Over-explainer is called out for under-explaining - yeesh.

So to him, I was too contextually immersed. I already knew how to work within this context and wasn't going to predict how inadequate his skills were, to the task. This happens so often to me, here in Austin - and believe me I'm not advanced.

I spend hours every week for years reading every ridiculous detailed post that Benny or Lars might make, only to have to research "WTF? What is a CSS variable? Oh, that."

You were correct, Pascal. Sometimes "I also think the JS community could grow up a little bit" too. But at times you guys have no idea how ignorant some of us are, on this channel. You have all picked up so much over the years (contextually immersed). My boss takes one look at a WC and asks "how do I import bootstrap and jquery?" It's a different world.

Okay yeah, thats fair. I do relate to that, in my blogposts I always try to make things as accessible/approachable as possible as well. In docs especially its a hard balance to strike as well. Its definitely something we can keep in mind moving forward.

I do want to clarify a bit though:

"I also think the JS community could grow up a little bit"

What I meant with this was that I think its a bit childish to make toilet jokes because of the 'wc' in the name - i definitely was not referring to different levels of development knowledge

I finally took time to read this and I 100% agree with @web-padawan.

We've had a lot of discussion on this topic within the team, and will have another discussion on it this weekend. We should be able to share some more info on this soon :)

Quoting and fully agreeing with @thepassle

Imo open-wc should be all about getting started with web components, and making it easy for people to build web components or apps with web components. This includes guides/codelabs/examples, but also build/test/lint etc configurations. We've also discussed giving more advanced/in-depth guidance on building apps.

I truly do not want to see "how to use WC with Vue" or "how to use WC with React". I don't even think tools that are usable by other frameworks should even mention those other frameworks on open-wc. Those specific tools have their own documentation on how to use them with other frameworks. What is missing from most of those tool's sites are how to use them with standard web components. And that is where open-wc fills a gap.

@LarsDenBakker, I gather that https://github.com/modernweb-dev/web is the direction that this is headed? Could we get perhaps a broad overview/philosophy of how the @open-wc projects are going to get split between the two org repos? It's great to see this project maturing.