expressjs
Redesign of the Express Documentation
Over the time we had commented that we want to "refresh" the website, in the past Node.js requested support from the foundation to hire a designer to refresh the website completely. Is this something that we want to explore? Do we have the resources to support this process? I assume that we need to do a great work of content curation, etc... prior to start the re-design process.
Anyway, I am creating this issue to have a common point to discuss it and track the evolution (cc: @expressjs/docs-wg @expressjs/express-tc @bjohansebas @micheleriva @AugustinMauroy)
IMO before asking for a developer we need to know which website structure do we want.
@UlisesGascon, @AugustinMauroy, one of my two co-founders (@nglngl) is a designer. We can offer our help for redesigning and most importantly for facilitating any discussion around the redesign, if you find it useful
Honestly, help like this would be very useful for the website. Having something well-defined to improve the design would be great. For example, we have several issues like #1780, #1702, #1758, and #1760 that propose changes to the current style.
Recently, we also changed the dark mode colors, and there are many things I would still like to change. However, the problem is that I am not a designer, and I don't know if the other members are either. I’m not sure how things should be structured to provide the best experience and give the website a fresh look.
Sometimes, we have had to revert certain changes, like #1668, which was reverted in #1732. Initially, it seemed like a good idea, but due to accessibility concerns, it wasn’t. Situations like this might keep happening because there isn’t a clear design guideline.
It’s also true that we’ve taken a lot of inspiration from other documentation sites, such as Node.js, Vite.js, and Electron, among others, to try and achieve a fresh style.
Hi there! I really appreciate @AugustinMauroy's comment:
IMO before asking for a developer we need to know which website structure we want.
This is something where I'd like to help too. I can structure a small workshop where in 45min we can try to understand what kind of structure, style, and features you want on the website. That's part of my daily duties at Orama and I've been doing this for the past 15 years, and I'd love to contribute.
This would also give me a good direction for proposing some designs if you agree. We can sponsor the activity as Orama (we have a strong design team and of course, engineering too) so we can help both on code, design, and overall website structure.
I'm on the OpenJS Slack channel too (my full name is Angela Angelini there) and I'm happy to continue the conversation either on GitHub or Slack :)
That sounds great! I'll ping the other members privately on Slack so they're aware of this and we can coordinate a meeting.
Thanks for the offers to help @micheleriva @nglngl !
I'd like to clarify what's meant by "design," as the word is often used to mean various things. In my mind, there are three distinct areas that could fall under this rubric:
- Visual design: The content display, layout, and typography. In other words, how a page appears and its overall UX, including responsive display and accessibility.
- Information architecture: How topics (pages) are structured, aka content taxonomy.
- Navigation mechanism: How the reader navigates through the topics (content) on the site.
Although related, these are separate topics and IMHO it makes most sense to address them separately.
- Item number one is what I generally think of when I hear "design."
- Item number two (info architecture) is complicated and very important, and in my mind is outside the scope of "design" per se.
- Item number three is also important but in technical documentation is almost universally implemented using a left-side navigation panel, sometimes with a right-side sub-navigation, ie. within the page. IMO, we should consider moving to a navigation mechanism like this. Currently https://expressjs.com/ uses a horizontal drop-down navigation menus, which IMO we've outgrown. Compare that to some other prominent tech docs in the JS world:
- https://docs.angularjs.org/guide
- https://nextjs.org/docs
- https://svelte.dev/docs/svelte/overview - This site also has an interesting "landing page" to help new readers.
So, I want to clarify that we are discussing visual design (item one above) here.
We should also discuss items two and three, but those are separate topics. IMO, item three is a solved problem and we don't need to "reinvent the wheel" but we can certainly discuss other approaches.
These are good points. When I was referring to improving the design, I was talking about points 1 and 3, which for me are the areas where a designer could help us, and in which it would help give a fresh and modern style to the website, similar to what was done in Node.js.
@nglngl, @micheleriva On behalf of the whole team, we are happy for the help you offer us, and we would like to participate in the small workshop.
We were thinking that we could discuss this in more detail during our working session on the 26th (reference). We could dedicate part of the session to this topic, along with other important discussions like automated translations, the tech stack, and more—so we're all aligned for the upcoming milestones.
What do you think?
Would you (@expressjs/docs-wg @expressjs/docs-captains @crandmck @nglngl @micheleriva) be able to join?
Hey @ipreencekmr, @ShubhamOulkar, it would be great if you could attend and participate since you've been active lately.
@nglngl, @micheleriva On behalf of the whole team, we are happy for the help you offer us, and we would like to participate in the small workshop.
Amazing, we are happy to help. The 26th works fine for us! Roughly, how much time do you think we will be able to dedicate to design?
I think we wanted to make sure we are all on the same page. With @crandmck's comments above and some other ongoing work, we were concerned that we maybe weren't all clear on the goals. From our discussion on the call yesterday, I think our hope was to get that alignment on the call on the 26th. Especially kicking off something larger like this, we didn't want to skip past the planning too fast 🤓.
The recordings of the two meetings:
26 Mar: https://zoom.us/rec/share/1AmCA5SwXqqrUz955KP75cstAFOVixKNpH-m_fHThEyWiEcSYseYPYOTrFTvHHlp.F57ZT60jJsbseynB
9 Apr: https://zoom.us/rec/share/6n7vvfNAAAVfySBy3a5AGkrNqvHj_3dYuRXL8o4_l66HTCW_FATPuonSbsDJ12F1.0mjZrubIPNZI2TQ0
cc: @expressjs/docs-wg
May 7, 2025: https://zoom.us/rec/share/CgYDak4tdRtVM6Jy7bqyPK7S24rswMNM5k9vfxJf7Vr0EiTvA-yqvnZDp-MJ7L2x.4CtIQe5soCAUclZd
May 21, 2025: https://zoom.us/rec/play/c5nVMGA2oATvofQfawNXAIeBaquN7zSvrLv55WeZ4hTswbpALhJEGStxFH-qi81Q0dAHIL0oBzFQsX8W.O4ADsgmnO4I88gDw
May 7, 2025: https://zoom.us/rec/share/CgYDak4tdRtVM6Jy7bqyPK7S24rswMNM5k9vfxJf7Vr0EiTvA-yqvnZDp-MJ7L2x.4CtIQe5soCAUclZd
May 21, 2025: https://zoom.us/rec/play/c5nVMGA2oATvofQfawNXAIeBaquN7zSvrLv55WeZ4hTswbpALhJEGStxFH-qi81Q0dAHIL0oBzFQsX8W.O4ADsgmnO4I88gDw
Hi @UlisesGascon, I just finished watching the recordings — thank you for putting them together! 👏
Here’s some feedback from my side,
- I think we should set a milestone for the website redesign to track progress more clearly.
- Have the Figma design links been shared with you? I'd love to contribute to the Figma work if possible.
Regarding the May 21 video, I noticed it focused mainly on Orama's search bar and its capabilities. I'm a bit unclear — who is currently leading or working on the website redesign?
Lastly, I think Proposal 03 for the logo looks great! I do have a small suggestion for a modification, if that’s allowed. Also, Proposal 02 looks great as well, but it might need some adjustments for selected text. I think it would be good to do some testing to evaluate how it performs in different scenarios.
June 18, 2025: https://zoom.us/rec/share/__IW4511ve2ffNZSdhBV6t96Jc4RuDbgwLtfk_nLZtvY3acP2hZhma4ez8h7jXQB.hACh_IVnXrXlEyjp?startTime=1750277222000
Figma: https://www.figma.com/slides/S4aF97PTSNQPOpCACXgrD6/Express---brand-proposals?node-id=78-629&t=Mn7onkJoPfyxVASZ-1
Hi @nglngl, I was thinking about the design, the documentation pages are missing a ToC, it would be great to include it in some way. We also often have announcements that would be great to display on the main page, just like Node.js does and as we currently do.
Or at least I don't remember seeing it when you presented it.
P.S. Once we have the Figma where the proposals are being worked on, it will be published here.