search

eslint / archive-website

The ESLint website
https://eslint.org
MIT License
95 stars 244 forks source link

Proposal: Split up website #867

Closed nzakas closed 2 years ago

nzakas commented 3 years ago

Background

Since the beginning, the ESLint website has always had a mix of several different purposes, and each purpose has its own lifecycles and uses. At best, we can break up the website into the following sections:

Section Base URL Update Frequency
Blog /blog Periodically
Demo /demo Every release
Documentation /docs Every release
Marketing Homepage and /about Rarely (mostly sponsor logos)

There's always been a weird relationship between the eslint repo and the website repo, consisting of us copying files over from the eslint repo into website during each release.

Problems

While there are no significant issues, there are a few lingering problems.

  1. The tight coupling between website and eslint repos makes it very easy to break, and when broken, it can be difficult to manually clean up a release.
  2. There is still a lot of confusion over how to fix documentation. We still get PRs to website that need to be in eslint. This has remained a consistent headache since the project began.
  3. The demo feels very bolted-on. We've tried to make it work, first with Jekyll and then with Eleventy, but it really doesn't fit into the static documentation site mold. This makes it difficult for outside contributors, and even team members, to feel comfortable making changes.
  4. No way to better organize documentation with UI from within the eslint repo. Once again, this makes it difficult to make significant UI changes during a release due to the coordination involved.

Proposal

I'd like to propose that we split up the website into three, standalone sites:

  1. eslint.org would contain the marketing pages and /about pages. This would continue to exist in the website repo. We'd ensure that all of these pages are evergreen, or in the case of sponsors and team members, auto-generated. The intent is that we will continue rarely changing these pages. We could rename the website repo to eslint.org.
  2. docs.eslint.org would contain the release-specific documentation. This would exist in the eslint repo and be deployed from there during a release. This would mean the entire website would be in the eslint repo, not just blank markdown files.
  3. play.eslint.org would be the demo, rebranded as the playground (to better fall in line with terminology used by other tools). This could exist either in its own repo, play.eslint.org, or inside of the eslint repo. I'm leaning towards a separate repo because I think it would be easier for people to find and contribute to.

Benefits

Some of the benefits I see of this approach are:

  1. Clear separation of concerns between repos and what content they are responsible for. No more duplicate content.
  2. ESLint release can be done within the eslint repo without coordinating with another repo.
  3. We can use separate tools for each website that is appropriate to its use. For instance, we could continue to use Eleventy for eslint.org, we could use Nuxt for play.eslint.org, and Docusaurus for docs.eslint.org. (These are just an example! I'd like to us to evaluate what we'd actually use before making any final decisions.) The ability to use the right tool for the right job seems like a big win to me.
  4. We can build out play.eslint.org to do more than it does now without burdening the marketing pages.

Downsides

  1. It will take a bunch of bootstrapping work to implement this.
  2. We'll need to set up two ad accounts, one for eslint.org and one for docs.eslint.org, which is more overhead.
  3. Fixes to docs.eslint.org will be tied to releases. (This is true now for content, but not for UI bugs, which we can fix at any time.)
  4. Potentially makes translating the content more complex if we want to include both marketing pages and docs.

Thoughts?

I'm curious what folks think. This would be the biggest change to how we manage our docs and the website since the ESLint project started, so I know it will be a lot of work and need more planning than I've indicated (probably an RFC). At this point, I'm just looking for feedback.

nzakas commented 2 years ago

TSC Summary: This issue proposes splitting up the website into three sites:

  1. The marketing site (homepage, blog, sponsors, about) to be stored in the website repo.
  2. Documentation site (docs.eslint.org), to be stored in the eslint repo.
  3. Playground site (play.eslint.org) to be stored in a new play.eslint.org repo.

TSC Question: Do we want to pursue such a change?

nzakas commented 2 years ago

This is complete! 🎉