Docs & design overhaul - Githubissues

sk1nzz commented 3 years ago

Hi there. It's 2020 and Express remains the most popular Node framework. However, we still have an obsolete docs site that doesn't meet today's design trends.

I think it's time to:

rebuild the docs site with modern static site frameworks like Gatsby;
update the Express logo and implement a design system for the docs.

Your opinions?

rodion-arr commented 3 years ago

Hi, I assume core team is focused now on pushing next major express version. If you have something to propose opening a PR is more than welcome!

crandmck commented 3 years ago

PRs always welcome, of course, but this proposal would be a significant project. Does Gatsby have a GitHub integration? That's one of the main advantages of Jekyll.

hunvreus commented 5 months ago

I'd be more than happy to contribute to this, but not sure pushing a massive PR would be helpful.

I'm assuming there are several people involved in maintaining the website, I think they should be involved in the process at the very least with regards to UX and sitemap.

It would likely take several steps to get to an updated version of

Stack: I don't mind sticking to Jekyll. We could certainly move to another SSG (e.g. Eleventy) but I'm not sure that would address the key issue (UI and UX), although it could help if the current build process is too slow. I do think it'd be helpful to adopt a modern CSS framework though (e.g. Tailwind).
Sitemap: I think there should be a concerted effort to review the current pages/sections and figure out what would make sense for the projects (AND the site contributors). I'm not sure there are analytics on the site, that could be helpful figuring out what folks are actually looking for.
Design: expectations aren't what they used to be when this website was designed, even for Open Source project. I think the current design is a bit damaging to all the hard work that the maintainers are putting in. This could however be the more contentious point for Express.js collaborators (it's always difficult to get a group to agree on UI choices). I would also say that a very light refresh of the wordmark wouldn't hurt, but I wouldn't want it to distract from the UI/UX work that needs to be done.

Happy to put in work there, but again I'm mostly concerned with how we should break this work down.

I'm fine with either:

Option 1: breaking things down in a bunch of small incremental improvements,
Option 2: make a big redesign push we can refine until we're comfortable with the changes.

@dougwilson I'd be curious to know who leads on the expressjs.com front (yourself?) and where contributors hang out (IRC seems dead and Gitter mostly looks like user support).

jonchurch commented 5 months ago

There's a lot to be said about a docs and design overhaul.

But let's break it down slightly

Docs

The content of the documentation itself is due for shaking the dust out and improving. A full rewrite would be costly in man hours and overseeing it, but would be worth considering. Incremental changes to the corpus in the meantime are the most likely to get merged.

Design

The actual site on which the docs are consumed. Same thing goes in terms of shaking out and improving, and how scope impacts likelihood to get changes landed while maintenance is ramping back up.

The Question is, which do we prio first?

Here's a tracking issue where these dicussions will be gathered https://github.com/expressjs/discussions/issues/211

I'd prefer we prio the content of the docs, and lean on some existing software to turn that into a really good hostable docs site. The point of the website is to host the docs and guides. I see the site as an entrypoint to the docs, and should be no more technologically complicated than necessary to facilitate that.

to answer your question @hunvreus @crandmck leads in this repo, doug is a TC member as is rand, but rand specializes in technical writing

crandmck commented 5 months ago

Thanks for the discussion @jonchurch @hunvreus ... I'm getting re-engaged with the project after some absence, and the project as a whole is being reinvigorated with short-term focus on the 5.0 release. But still, I'm working on this in my spare time (as most of us are), which is sadly limited.

I agree with @jonchurch that content updates should be the top priority. Certainly, we can improve the presentation (i.e. framework, css, etc.) but that is secondary to the actual information.

See https://github.com/expressjs/discussions/issues/211 for more of my thoughts.

Immediate priorities are reviewing/landing open PRs and issues and preparing for 5.0 release. After that, we can reassess.

expressjs / expressjs.com

Docs & design overhaul #1206

Docs

Design

The Question is, which do we prio first?