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.
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.
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.
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.
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:
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.
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.
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:
Clear separation of concerns between repos and what content they are responsible for. No more duplicate content.
ESLint release can be done within the eslint repo without coordinating with another repo.
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.
We can build out play.eslint.org to do more than it does now without burdening the marketing pages.
Downsides
It will take a bunch of bootstrapping work to implement this.
We'll need to set up two ad accounts, one for eslint.org and one for docs.eslint.org, which is more overhead.
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.)
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.
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:
/blog
/demo
/docs
/about
There's always been a weird relationship between the
eslint
repo and thewebsite
repo, consisting of us copying files over from theeslint
repo intowebsite
during each release.Problems
While there are no significant issues, there are a few lingering problems.
website
andeslint
repos makes it very easy to break, and when broken, it can be difficult to manually clean up a release.website
that need to be ineslint
. This has remained a consistent headache since the project began.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:
/about
pages. This would continue to exist in thewebsite
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 thewebsite
repo toeslint.org
.eslint
repo and be deployed from there during a release. This would mean the entire website would be in theeslint
repo, not just blank markdown files.play.eslint.org
, or inside of theeslint
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:
eslint
repo without coordinating with another repo.Downsides
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.