Redesigning Nodejs.org: Part 1
A Competitive Case Study
The Node.js website has not had a significant content and Information Architecture (IA) update since early 2014, and a lot has changed since then! Design trends have shifted, the competitive landscape has become more crowded, and the Node project has achieved new heights in the developer community. The world runs on Node, and I believe the condition of its public image should match the quality of its code.
To help kick-off the Node.js website brainstorm in the Github Repo, I’ve taken a look at ten of the biggest-name developer platform websites out there, and synthesized some of my favorite IA choices, design elements, and interaction features into a list of recommendations for Node.js’ upcoming website redesign.
Note: I know I’ve missed plenty of amazing features out there — this article is by no means exhaustive! Please comment at the bottom with your favorite developer experiences from across the web.
The State of Developer Websites
What goes into a great developer documentation site? Programming language and frontend framework sites tread a fine line — they need to be both inviting to newcomers, while remaining a valuable resource for power-users.
When I first began this process, I was planning to keep this review exclusively to programming language sites, but I soon discovered that these sites were rather…well…boring.
It turns out that frontend frameworks dominate the market for exciting and innovative documentation site designs. I believe this is for two reasons:
- These sites are made by web developers, for web developers, on the platform they’re designed for, and;
- The intense competition in the frontend framework space forces these projects to aggressively fight for market share and constantly improve their marketing and outreach efforts.
Taking this insight to heart, I ended up reviewing ten (10) Programming Language and Frontend Framework sites leading their respective spaces to gather ideas for this article. These are, in no particular order: Scala, Rust, Dart, Ember, React, Angular, Vue.js, Go, Swift, and Ruby.
If you are so inclined, you can find my stream-of-consciousness, largely unedited, notes on these ten developer documentation sites here:
Aesthetics
The look and feel of a website must represent the principles and values of the project. Luckily for us, at Node Interactive 2017 in Vancouver, the collaborator community ran an exercise to help identify some of the Node.js Core Values. This was only the first of many Node.js Core Values workshops, but it gave us a wonderful springboard to launch a redesign:
Node is: Stable, Inclusive, Welcoming, Performant and Fun
Let’s compare these concepts to the current site design:
✘ Welcoming: Large gray blocks bookend the viewport, constricting the content and send a stand-offish message.
✘ Inclusive: Green on dark gray does not perform well for fully colorblind members. Cold writing gets the message across, but not much else.
✘ Stable/Performant: The clunky layout, haphazard typography, and lack of vertical rhythm does not scream professionalism.
✘ Fun: … I love corporate grays!
Thoughts for Improvement:
- Lighten Up! The dominating color in this design is dark gray. Done well, this may look professional, but is rarely described as “welcoming”. Expanding the color palette to include light grays that compliment the brand color (or even *gasp* a second color?!) will increase the site’s expressiveness and afford more options to designers..
- Pick an Illustration or Photography Style: A little imagery goes a long way to humanize a site. This will help make visitors feel welcome and paint the site as friendly, engaging, and helpful place to explore.
- Typographic Hierarchy / Vertical Rhythm: Having well-defined content hierarchy and rhythm pulls the design together and screams “stable and professional” like nothing else. This extra layer of polish will inspire confidence
- Play With Shapes: The Node logo is beautifully geometric. Use this design to help inspire novel, interesting, and dynamic layouts and visual elements that mirror the logo. This will help keep the site feeling on-brand, and add a little spark of fun to the property.
- Find Your Voice: Tone is important. When users arrive on NodeJS.org, they’re here to learn something. They are entering a strange, foreign place in a potentially vulnerable, “should I even be here”, state of mind – it’s important to talk to them like a friend! The most effective documentation sites I’ve encountered strikes a delicate balance between dry, technical content, and casual, conversational presentation.
Navigation
Navigation anchors visitors on your site and provides a guidepost to keep them from getting lost or overwhelmed. Documentation sites inherently have a lot of content. It is the navigation’s job to keep this organized and un-intimidating.
Here’s a good rule of thumb: Only present between four and six main navigation items to the user, or run the risk of choice anxiety.
Instead, guide the user where they want to go, presenting small, bite-sized choices along the way.
To accomplish this, many sites present secondary nav or an in-page accordion menu.
This need for simplicity doesn’t mean we can’t have a little fun with the nav though! React highlights the latest release version in its nav at all times, and Go allows you to open up an editor and play with code from anywhere on the documentation site.
The best way to determine if an item belongs in the nav is to ask ourselves this question:
What are users here to do 90% of the time they visit?
By answering this question, we can easily keep the nav parsable and reduce choice anxiety for new-comers to Nodejs.org.
With all this in mind, we can now make a few recommendations for the Node.js website. Currently, Node presents eight options to users in their main navigation. I recommend we whittle this down to six:
The grand majority of existing content fits into these six pages. However, there are a number of important pages that don’t fit in to this nav structure. For example: Governance, Security, Legal, Brand Assets, etc.
These pages do not meet our 90% use case criteria, so they are absent from the main navigation. Luckily, we have a oft-forgotten place to surface these still very deserving pages: the site footer! Too often the footer is forgotten about as a valuable place to store navigation that is important for users to find easily without adding cognitive overhead for the majority of visitors.
So, lets review these six major sections one-by-one, shall we?
Homepage
The home pages of developer documentation sites have undergone a steady shift in the past decade. What used to be a dry presentation of facts, has evolved into highly focused marketing and social appeals. The welcoming and inclusive tones these brands have struck seem to say “you can get the job done and have fun while you do it”!
This shift to active marketing is more obvious in the far more competitive frontend javascript framework space, but can also be seen creeping into programming language’s websites. These projects tread a fine line between professional whimsy and dilettantish immaturity, but always seems to fall on the side that is workplace appropriate — a difficult needle to thread.
Marketing pages, of course, always start with something that should look very familiar to us experienced web navigators: The Hero Banner.
This component is frequently followed by another familiar marketing pattern: The “One-Two-Three Sales Pitch Punch” (name patent-pending).
It is also very common for sites to have a prominent “ad-unit” space to up-sell upcoming events and conferences they are hosting.
Some of the most delightful experiences on these documentation sites are the live code examples. They allow users to get their hands dirty fast, with zero effort, greatly reducing cost for buy-in.
The homepage is also a place to brag about your sponsors and major consumers – I call it the “Appeal to Authority Pitch”.
Don’t get me wrong here, these sites are not all cookie-cutter layout — there are also some novel takes on developer homepage components:
If we want to get really crazy with our homepage page design inspiration, we can take a look at the latest and greatest self-promoters – sites that won Webby awards in categories such as “Professional Services”, “Financial Services/Banking”, and “Web Services / Applications” – to witness the largest cutting-edge trends in splash page design:
In 2017 there was a trend toward bold, kinetic, full page marketing experiences. It may benefit us to borrow the design trends from bleeding edge sites like these moving forward.
Learn
Nearly every site reviewed has a casual, conversational-tone, guide to getting started with the framework or language. The content presented here lowers the barrier to entry for the platform, enabling the community to meet the “inclusive” and “welcoming” culture mandate.
This entire section is conspicuously missing from the Nodejs.org website! It is somewhat covered by the deeply hidden Guides page, but not to the standard expected of modern documentation websites.
Many “Getting Started” sections take a very similar format: long scrolling pages that read like a series of casual blog posts, split into well-communicated lessons that follow a well-defined learning path. By the end of the entire process, you’re an expert in that product! Well, maybe not an expert, but at least you know enough to be dangerous.
These lesson plans are often visualized with long secondary accordion menus like these:
These secondary menus are well suited to visualize “learning paths.” They let the user see the full lesson plan, prepare for what is coming next, and rejoice in their sense of accomplishment once they reach the finish line.
However, by taking lessons from other products whose job it is to educate, we may be able to further improve upon our future “Getting Started” page. These secondary menus are reminiscent of similar features in learning tools like LinkedIn Learning, Khan Academy, and even the video playlists on YouTube. If we take leaf out of their books we can help our newest members learn even more.
Some documentation sites try to take these lessons to another level. In particular, the “Go Tour” provides an interactive lesson to teach its users how to code in Go. This format is often used on self-directed learning platforms like CodeAcademy and FreeCodeCamp.
I believe a hybrid format may be effective – display a “learning paths” secondary menu, with optional exercises in each section for users looking for a more tutorial-like experience.
Whatever the presentation, a Getting Started section is a must-have for any modern documentation site.
Documentation
Unlike the “Learn” section, the documentation section is all about raw API information. This is the down-and-dirty, low level information that power users want fast access to.
However, just because these are power users, doesn’t mean the API browsing experience can’t be pleasant! The best API guilds are quick to navigate – it can’t take too many clicks to find the method you’re looking for or else… Whoops! There goes your laptop out the window.
Two of the largest offenders of difficult-to-navigate API documentation are Rust and Angular. To navigate the docs, the back button almost required. Remember: Clicks are expensive, scrolling is cheap, and side-menus are your friend.
Great API docs not only navigate well, but read well too. Just because this is the “dry” section of you site does not mean it has to be boring!
Versioning documentation is especially important in the fast-moving JavaScript ecosystem. With a new major version released every six months, Node is on a relatively fast release cycle compared to other programming languages. Because of this, and the tendency for many different versions of Node to be actively used in the wild, it is extra important that users can quickly and easily switch between API documentation versions.
The Node site does currently provide a list of all past documentation versions, but once on the API docs site, there is no way to switch to another version easily. Many users will come directly to the API documentation from a google search, or Stack Overflow link, and may need a way to switch versions right on the page. Version drop-downs are the standard way to accomplish this:
The content of the Node.js API documentation is well-written, comprehensive and informative. However, the presentation leaves something to be desired and could use a good re-design. The documentation is missing a comprehensive Architecture section. It may also be valuable to split C++ Addon and N-API documentation into its own section.
Releases
The Releases section is often labeled “Downloads” or “Install” on other websites, and I have a hunch the name of this section will be controversial 😉
I opted to title this section Releases for two reasons:
- The CTA for “Install” will be surfaced both on the homepage as the primary CTA and in the “Getting Started” walkthrough. These are the primary paths to installation most new users will take.
- By calling this section Releases, we can surface information about release cycles, process and past versions in an easy-to-find manner. This preserves information hierarchy on the site and improves discoverability of other important content, while still presenting an easy path for discovery to users who may miss the “Install” CTAs elsewhere on the site.
The Releases section should contain these three sub-sections in a secondary nav:
The Releases home page will first and foremost display the install widget. This widget may be similar to the one Node’s current downloads page, but simplified to fit in the page header and streamline the installation process.
When we again think of the 90% use case on this page, most users will look for either the Windows Installer, Mac Installer, or Linux Binaries. By choosing to initially only show these three options – with a “Other Download Options” dropdown easily available to accommodate the long-tail use cases – we scale down the size of this module, and reduce complexity on the page. Clicking the “Other Download Options” dropdown will expose all the detailed download options, that are currently always visible, for power users.
By simplifying the visible installation options to our 90% use case, we now have nearly an entire page to supply valuable information about the Node.js release process!
By explaining the Node.js release process and timeline in easy to understand terminology, we invite users into the fold, making them feel an even closer part of the development process. This removes a shroud of unintentional secrecy that kept the release process at arm distance, and encourages emotional investment and ownership of Node.js.
Nothing in the market explains complex release cycles better than the Ember Builds Page:
Like the Ember site, the release process visualizations on nodejs.org can be driven by Node’s release schedule JSON file for a more engaging and informative experience.
Navigating to the “All Releases” or “Nightly Builds” page will show a list similar to the current Previous Releases page. However, we may wish include a engine switcher to select V8 or ChakraCore, and an option to select/filter build targets, to help consolidate leaf pages. SHA257 Checksums may be displayed in this list to like the Go downloads page to consolidate leaf pages even further.
Okay, ready for a crazy, pie-in-the-sky, idea? As an alternative to the installation widget on the Releases home page, Node could choose to maintain a single installer script, like many other projects do:
I will rely on those more familiar with CLI installation scripts to debate the details, but there are many existing projects that Node can use as a foundation for a script like this, that will fulfill the majority of use cases.
Imagine if new developers could simply run:
curl install.nodejs.org | sh
And have the the most updated LTS release installed on their machines.
The intent here is to reduce 90% of installation use cases to a simple one line copy and paste.
The CLI installed could be as fully featured as nvm, or as simple as the one-time Rust installer. There are obviously many technical hurdles to overcome in a tool like this, and details of this feature would be better left to the Technical Steering Committee, if it is even possible at all.
Regardless of installation implementation details, the core responsibility of this page remains the same: Allow installation of Node versions with as little friction as possible for the 90% use case user, while providing an escape hatch for power-users that may require more specialized support.
Community
Community pages, by their very definition, contain some of the most human content on a developer website. Because of this, it is impossible to cover all of the possibilities for content and presentation in this article – they deserve a blog post all of their own!
That being said, this article will not delve into specific layout recommendations. Instead, it presents a smattering of ideas and offer structure and help inspire debate as the community begins its discussion. It also, surprisingly, has to make the argument for having a community page in the top-level navigation at all.
Why Promote Community
Thats right, the current Node.js website does not contain a dedicated community page! There are pieces strewn about with related material, but despite the Node core values of being Inclusive, Welcoming and Fun, the website does not currently put its community front and center.
Community pages on other sites in this space function as launchpads into the larger ecosystem that has emerged around the product. Node has one of the richest ecosystems out there, and it is a crime to not showcase the amazing resources this community has developed!
Community Taxonomy
On the sites reviewed, community resources broadly fit into these eight categories:
- Comms: Forums, Mailing Lists, and Chats
- Jobs: Job Discovery Resources
- Conferences: Conf. Info, Past and Present
- Community: User Groups, and Meet-ups
- News: Official and Non-Official Publications / Podcasts
- Education: Community Powered Learning Resources
- Tools: 3rd party Libraries and Tools
- Collaboration: Instructions for Contributing Code and Reporting Issues
The five best examples I found of robust community page content appeared on the following pages:
Scala Community Page | React Community Page | Rust Community Page | Ember Community Page | Angular Resources Page
But it takes more than just long lists of content to have an engaging community page! These endless lists easily become overwhelming for those just beginning their developer journeys. React and Rust are particularly bad offenders. Sure, the content is there, but it isn’t welcoming or explorable.
Community Design
Much of these discoverability issues are, as usual, easily overcome with good design. The eight sections outlined above are all extremely different types of content. It can therefore only be expected that their presentation requirements are also extremely different.
There is no website reviewed that I can point to and say “they did it perfectly”. But, there are a few shining examples of engaging design to showcase:
Overall however, this space is ripe for innovation. My advice: First determine the content Node will provide for each of the eight sections outlined above. Then – don’t just throw it all in a markdown file and call it finished – go out into world and find beautiful examples of that genre of content presented effectively.
For example:
News: Are we displaying lists of articles or publications? Medium has that down to a science.
Comms: We can look to platforms like Gitter or Slack on how to best present lists of chat rooms. If you’re an especially astute reader, your’ll notice this presentation looks familiar to Scala’s Comms Channel widget!
Conferences: Major conference organizers like Dot Conferences have some very attractive methods to display their conference selections.
Contribution Guides
This article recommends that contribution guidelines also live under the Community moniker. However, on many sites contribution is important enough to get a top-level nav item.
Regardless of location, these pages are typically more information dense than other sections of the site. That is okay, because by the time a visitor begins exploring these pages, they typically are already bought in to the extra work of digesting dense documentation. As always though, use best judgement when drafting these guides – nobody likes a wall of text, no matter how advanced your coding skill.
Blog
There are so many articles on the internet arguing about exactly how dead – or un-dead – blogging has become in the past five years. Since the rise, and subsequent world takeover, of social media, dedicated blogs have begun to take a back seat to well-crafted social media strategies. Despite this, many documentation sites still have a dedicated blog – why?
If you ask all ten sites reviewed in this article, you are likely to receive twelve different answers. However, this author believes documentation blogs have a singular purpose: Nitty-gritty release notes and change logs. After all, as a famous man once said…
Keep it to the point!
- This Author, Dec. 2017
Despite our best intentions, the project documentation website is not where the majority of users discover news about the platform. That is the job of Medium, Twitter, GitHub, YouTube, community mailing lists, etc. These channels are designed to maximize social reach, and deliver content to where your users already are.
Blogs like those on the React, Go and Scala websites have an ineffective mix of fluff pieces, release notes, and feature showcases.
Blogs like those on the Ember, Ruby and Angular websites almost exclusively publish release notes, low-level feature progress reports, and security updates, or just link out to a Medium publication.
Luckily for us, the Node.js blog already largely follows the release-blog model! My one recommendation is to add an up-sell at the top for users looking for Node’s community blog and migrate any more community-focused pieces to the Medium publication backdated articles and finalize the split in responsibility.
Footer
Bonus section! As mentioned above, the footer is a wonderful home for pages do not meet our 90% use case criteria. This content is important enough to have a link surfaced on every page of the site, but is not required for all users to see the second they arrive. Even though these pages are less visible than their primary-nav counterparts, they deserve to be designed with just as much care and attention to the user as any other top-level content.
These pages may include, but are not limited to:
- Governance
- Security
- Legal
- Brand Assets
- Team
- Link to Node Foundation Site
Moving Forward
I hope this article serves as a launching point for discussions in the Node.js community about next steps. This competitive analysis is just the beginning of a long design process, and I am excited to join the conversation!
Keep an eye out for follow-up articles with walkthroughs of site wireframes, high fidelity mocks, and hopefully soon, a full breakdown of the newly re-built nodejs.org 🎉
Please feel 100% free to comment at the bottom of this article with your favorite developer experiences from across the web, or join the ever on-going conversations happening on the Node.js Github Repo – there’s a lot of work to be done, and I look forward to seeing you there!
