Redesign of Node.js Website

[ovflowd]

Hey, y'all 👋 as many know, for many years, there were multiple efforts to redesign the Node.js Website.

Recently, the Foundation has stepped up with a professional designer to make another iteration of a redesign of the Node.js Website. The primary intent behind here is that the current design on nodejs.dev was done by a previous team, and it already started to look old before even being released. It was also an incomplete design, and we could never reach out to the original designer of that Node.js Website Redesign to get clarification on certain things.

The Foundation (Robin, Kylie, and Ben) and a few Node.js members (Rich Trott, Joe Sepi, Richard Lau, and me) have been working on and evaluating a new design revision of the Node.js Website.

I'm incredibly excited with the new revision as we addressed many topics pertinent to the project and developed a Design that is simple, modern, and addresses the current Website issues (design-wise, feature-wise, and content-wise in a certain way).

After a few months of work, the design is completed, and we're ready to present the final designs to the TSC. I understand that the Website Team has autonomy over the website's technology. Still, when it comes to content and design, we want to have feedback from the TSC and understand if there are any current propositions of the design that the TSC would not feel comfortable with.

I'd be more than happy to present and iterate through all the new design elements and answer all questions the TSC has at the upcoming TSC meeting.

cc @mhdawson and @Trott for the meeting agenda.

I'm also dropping the Figma link here for anyone interested in already looking. The TSC is more than welcome to drop comments on the Figma, but I would rather have them addressed initially on the call to avoid pollution of the Figma.

Cheers!

[ovflowd]

Also important to mention that me and @bmuenzenmeyer are already working on the Roadmap and project management (and Component inventory) of the new Components.

The new Figma's are also done to make styling these components easy.

Some of these documents are "confidential" because we don't want to display them to the public (yet); hence I'd be sharing them during our call. (Also to avoid people from already taking issues and working on stuff when things are not ready yet, or, when we're still organising things)

Here's the current Discussion thread of the Website Redesign: nodejs/nodejs.org#5131

[mhdawson]

I propose that we have @ovflowd do a presentation in the TSC meeting on August the 23rd. @ovflowd does that work for you?

[mcollina]

It would be good to receive some sort of digital preview we can comment too.

[ovflowd]

@mcollina you should be able to comment on the Figma, which is a preview.

[ovflowd]

I propose that we have @ovflowd do a presentation in the TSC meeting on August the 23rd. @ovflowd does that work for you?

Yup

[mcollina]

can you share access?

[ovflowd]

can you share access?

@mcollina the Figma link is mentioned on the description of this issue. What do you mean with sharing access 🤔 are you unable to comment there?

[mhdawson]

Not sure how to comment in Figma but two things I'd call out

1. I don't see anything related the key feature of the banner that we use for security releases etc.
2. The ability to find/download the tar.gz and tar.xz files seems to be hard to find (I did not find it) and even if it is there it seems very well hidden compared to the current design. I think it should be as easy as it is today to get the different targ.gz and tar.xz files for each platform/architecture as it is todya.

[mhdawson]

Also
3. Where will the change logs and the posts for each release show up? Under the blog post or somewhere else? Hard to tell from the examples.

[ovflowd]

I don't see anything related the key feature of the banner that we use for security releases etc.

There are indeed designs for banners, including for Security Releases. As shown in the image below, we have introduced two kinds of banners.

The ability to find/download the tar.gz and tar.xz files seems to be hard to find (I did not find it) and even if it is there it seems very well hidden compared to the current design. I think it should be as easy as it is today to get the different targ.gz and tar.xz files for each platform/architecture as it is today.

These are easily accessible through the Dropdowns. You just don't search for "tar.xz", just for the Linux Binary. There's also a tab for Sources, and that's where you'd get the "tar.gz"

In other words, we moved away from having a big table, to having a Dropdown.

Where will the change logs and the posts for each release show up? Under the blog post or somewhere else? Hard to tell from the examples.

We have explicitly designed a new Modal that showcases a certain release changelog and the people that made that release available https://www.figma.com/file/pu1vZPqNIM7BePd6W8APA5/Node.js?type=design&node-id=719-13332&mode=design&t=FELBJRa12sQvX6ob-4

Regarding Release Blog Posts as we have today, they will continue to be on the Blog Area. (As shown here https://www.figma.com/file/pu1vZPqNIM7BePd6W8APA5/Node.js?type=design&node-id=422-7925&mode=design&t=FELBJRa12sQvX6ob-0)

[mhdawson]

Is there an example of the drop down on how I'd get the tar.xz for Linux PPC. The pictures are a bit hard to read for me, but I saw something more like get me linux with nvm. If there are there then just a pointer to which picture I need to blow up to a readable size would be great.

[ovflowd]

Is there an example of the drop down on how I'd get the tar.xz for Linux PPC. The pictures are a bit hard to read for me, but I saw something more like get me linux with nvm. If there are there then just a pointer to which picture I need to blow up to a readable size would be great.

• https://www.figma.com/file/pu1vZPqNIM7BePd6W8APA5/Node.js?type=design&node-id=332-45900&mode=design&t=FELBJRa12sQvX6ob-4 this link is the screen where you would download the Linux Binary.
  • Example values for the 3 dropdowns:
    • I want latest Linux binary for ARM -> that'd give me a tar.xz binary for ARM
• https://www.figma.com/file/pu1vZPqNIM7BePd6W8APA5/Node.js?type=design&node-id=332-46041&mode=design&t=FELBJRa12sQvX6ob-4 this would allow you to download the source code, which is simply the tar.gz file

If there are there then just a pointer to which picture I need to blow up to a readable size would be great.

Note that you can zoom in on the Figma :D

[GeoffreyBooth]

One thing I find very confusing in nodejs.dev, and is replicated here, are these C and M and so on icons near the headings on the docs page. In the nodejs.dev case they’re especially confusing because there’s no tooltip or other hint as to what they stand for; I had to ask on Slack to learn that they meant “class”, “method”, “global” and so on. I would encourage you to maybe use icons instead, and make sure there are tooltips that explain them on tap/hover. (I understand that icons would probably be even less obvious as to what they stand for, but the intent—that they’re illustrative/decorative—is more obvious.)

[ovflowd]

@GeoffreyBooth FYI the Docs design is a mock and the only design that is unfinished. Also we're not going to implement this docs layout for now.

But feedback taken, tooltips make sense for me 🙃

[mcollina]

I missed the link!

[mcollina]

I've added a few comments on the figma

[ovflowd]

I've added a few comments on the figma

I've replied to some fo your comments :D

[mhdawson]

https://www.figma.com/file/pu1vZPqNIM7BePd6W8APA5/Node.js?type=design&node-id=332-45900&mode=design&t=FELBJRa12sQvX6ob-4 this link is the screen where you would download the Linux Binary.
Example values for the 3 dropdowns:
I want latest Linux binary for ARM -> that'd give me a tar.xz binary for ARM

So what may be confusing to me is that it is under "Prebuilt installer". There is no prebuilt installer for Linux. Also how would you chose between the pre-built installer for macOS or the tar.gz where both are available.

It will also now possibly take me two additional drop down selections versus just clicking on the right link on the existing page.

[ovflowd]

So what may be confusing to me is that it is under "Prebuilt installer". There is no prebuilt installer for Linux. Also how would you chose between the pre-built installer for macOS or the tar.gz where both are available.

@mhdawson these are just design mocks. There will be a Prebuilt Installer for Linux, yes.

[ovflowd]

It will also now possibly take me two additional drop down selections versus just clicking on the right link on the existing page.

I think the drop interactions are worth it. Instead of searching for the right thing, you're presented with it. I genuinely find the interactions easier and more friendlier to people than a big table with numerous options (on a non-technical perspective)

[richardlau]

So what may be confusing to me is that it is under "Prebuilt installer". There is no prebuilt installer for Linux. Also how would you chose between the pre-built installer for macOS or the tar.gz where both are available.

@mhdawson these are just design mocks. There will be a Prebuilt Installer for Linux, yes.

There's no prebuilt installer for Linux. In terms of what Node.js provides:

• Compressed packaged (either tar.gz/tar.xz/zip/7-zip) prebuilt binaries (all supported platforms).
• Prebuilt installers (Windows and macOS only).
• Compressed tarball (tar.gz and tar.xz) containing the source code. This is not the same as downloading the source from GitHub (stuff gets stripped out of the source tarball we provide). This is platform-agnostic.
• Docker images via DockerHub.

[richardlau]

I left some comments in Figma, but the question over the promotion of installing Node.js via third-party Package Managers is a more philosophical question. For most users, a package manager provides a more streamlined user experience, however those are maintained outside of the Node.js project (which is why they're on a separate page on the existing website that contains a disclaimer that any issues found need to be reported to the third-party package maintainers).

We could possibly now re-evaluate recommending nvm as it's now under the OpenJS Foundation and in most cases installs the same binaries that we (the Node.js project) release. I know that other collaborators have been giving nvm command lines in social media posts around Node.js releases.

[GeoffreyBooth]

Personally I think we should keep the package manager installations prominent, as they provide the best user experience for most users. (Maybe for Windows users we show the installer by default, and for other platforms the package managers.) There are countless other projects out there that show package manager installation instructions, and users don’t generally assume that those projects maintain the package managers or the integrations with them (i.e. wherever it’s defined what a particular manager downloads for a particular version). I think we can add a comment in the code block saying something like # Once the nvm team adds support for the latest version or whatever caveat we think we need, and that should be enough. I also think we should list many package managers, including n and Volta, and not try to push people toward nvm.

[richardlau]

I also think we should list many package managers, including n and Volta, and not try to push people toward nvm.

That is what we did in https://nodejs.org/en/download/package-manager (n is on there, Volta is not). It's not a "blessed" list -- anyone can open a PR to the website repository to add to the list.

[ovflowd]

Yup the intent is to list all possible package managers, and render their snippets on codebox as mentioned on @richardlau's link

[ovflowd]

BTW can I get a thumbs-up from the TSC that we can already start the work on the redesign? Albeit except the parts that are open to discussion?

Because regardless of those items, we can already work on the Components :)

[tniessen]

Node.js® is an open-source, cross-platform JavaScript runtime environment.

I do quite like that this is concise and that it doesn't sound like marketing material :)

[ovflowd]

Node.js® is an open-source, cross-platform JavaScript runtime environment.

I do quite like that this is concise and that it doesn't sound like marketing material :)

It's simple but also too simple IMO, I like the little marketing shenanigans for this case hehe

[ovflowd]

Also, y'all, after many iterations of feedback for the code examples, I've made several pushes with better examples that showcase Node.js latest and greatest.

Can you all please give an 👀 https://nodejs-org-git-feat-new-blog-pagination-system-openjs.vercel.app/ and react with a 👍 if it looks good or write feedback :)

[GeoffreyBooth]

For the workers example, I think the title should have the word “threads” in it somewhere, so like “Use Multiple Threads” maybe. And I dislike the comments with filenames, especially filenames with .mjs extensions since it’s an ongoing struggle educating users that that extension isn’t required for using ESM syntax in Node.

Here’s an alternate version that’s still really short but that uses the if (isMainThread) approach of the docs:

import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';

if (isMainThread) {
  const dataToProcessOffThread = 'some data';
  const worker = new Worker(import.meta.filename, { workerData: dataToProcessOffThread });
  worker.on('message', message => console.log('The processed data:', message));
} else {
  const processedData = workerData.toUpperCase();
  parentPort.postMessage(processedData);
}

[mhdawson]

@ovflowd thanks for adding to the agenda, we'll discuss next week. Would you like to attend or just get the feedback from the TSC based as a post on this issue afterwards?

[ovflowd]

@ovflowd thanks for adding to the agenda, we'll discuss next week. Would you like to attend or just get the feedback from the TSC based as a post on this issue afterwards?

Id appreciate if I could attend to also showcase all the pages and answer any questions, but only if my presence is needed.

[mhdawson]

@ovflowd looking forward to see you there.

[ovflowd]

So to recap what we talked on the meeting:

• Update Homepage left footnotes to mention it downloads for your platform
• Update Homepage right codebox Worker example
• Change Homepage examples from time to time?
  • Since it's a static build, we could only shuffle every 5 minutes, which is when the cache invalidates...
• Update Homepage left main paragraph (Open to suggestions of what we should write there)

Did I miss something so far?

[GeoffreyBooth]

That all sounds good to me. I know it’s a static build but couldn’t it choose a random tab to be the default tab on each page load? Regardless I think the shuffling is a low priority that can come later.

For stuff like that “mission statement” text, perhaps the way to handle this is for one of us to open a PR specifically for that text and then that PR can be where we hash out the best language? Is there a branch you’re working on that I could open a PR against?

[ovflowd]

The idea for the mission statement sounds good, want to lead the charge?

Regarding shuffling; the main issue is that by doing something exclusively client-side this cause some sort of layout shift as initial render will diverge from the next immediate re-render. There are paths we can research but since this is a small "nit" Ill rather do it later and focus our resources on the completion of the website

[GeoffreyBooth]

The idea for the mission statement sounds good, want to lead the charge?

Sure, is there a branch that I should PR against?

I’m not the one who suggested shuffling so I can’t speak for that, but personally I think if it’s at all complicated then file it in the backlog for later.

[ovflowd]

Sure, is there a branch that I should PR against?

Against main branch 👀 the text is on /pages/en/new-design/index.mdx

[mhdawson]

@ovflowd presented in the last TSC meeting, removing agenda tag, please re-add if/when needed.

[ovflowd]

Hey folks 👋 I'm excited to announce we're ready for the release of the Node.js website redesign. We're about to merge the final changes and (then some minor polish passes).

I'd appreciate it if we could do a final review with the TSC.

cc @nodejs/tsc

[ovflowd]

The idea for the mission statement sounds good, want to lead the charge?

Sure, is there a branch that I should PR against?

I’m not the one who suggested shuffling so I can’t speak for that, but personally I think if it’s at all complicated then file it in the backlog for later.

Hey @GeoffreyBooth do you still want to make a PR with revised copy?

[ovflowd]

According to the TSC meeting, there were no objections/blockers about the release of Node.js's Website redesign. I've also pushed the fixes requested on the TSC meeting regarding the Bitness Dropdown and the search results for API docs to forward to latest LTS docs.

cc @nodejs/tsc please react to this comment with a 👍 to confirm that you feel positive/OK for the Node.js Website team to land the Website Redesign next week.

[targos]

Do you have a link to the latest preview?

[ovflowd]

Do you have a link to the latest preview?

It's here nodejs/nodejs.org#6362