Redesigning Nodejs.org (Supplemental)
Exhibit A: Competitive Case Study Notes
This article is supplemental reading material related to its parent article. If you haven’t read the main piece yet, you can find it here:
Beware: Stream of Consciousness note taking below️
Inspiration for the parent article comes from the sources listed below. I have included my largely unedited notes on each site for posterity. Read at your own risk!
Aesthetics
Clean, professional, minimal, with a hint of whimsy. Clean text and simple layout present a no-nonsense focus on information. The simple language and distinct lack of visual fluff — theres not even a banner image — sends the same message that React promises developers: We do one thing and we do it well — lets get down to business.
Information Architecture
React’s site structure is surprisingly simple. Two buttons prompt you to “Get Started” or “Take the Tutorial”. There are brief marketing blurbs below the hero header so you can quickly get a feel for what React is about. Directly below that, we dive right in to code, with live code examples showing off core tech. The structure of this homepage is simple, but wonderfully effective. By simply skimming the page, a developer with some background in frameworks can get a very solid understanding of React without even diving into docs.
Nav: Navigation is simple, containing “Docs”, “Tutorial”, “Community” and “Blog”. Easy for developers of any level to find where they want to go. The nav also contains the version number of the latest release. Clicking this will take you to the github releases page. I like the omni-presence of this link — it provides nice context regardless of where you are on the site.
Docs: Documentation is split into five (5) sections: “Quick Start”, “Advanced Guides”, “Reference”, “Contributing”, and “FAQ”. It is a little unexpected to see “Contributing” under the documentation tab and it may get lost in the shuffle.
The “Quick Start” and “Advanced Guides” sections are plain-english walkthroughs of how to get up and running, and advanced topics of the framework with code examples interspersed. Well composed, attractive presentation, and easy to follow.
Under “Reference” we find the major React packages and their associated APIs. All methods and classes are all explained in good detail using plain-english. This is much more accessible to new users than simply having a generated API reference. There is a Glossary section of jargon that new users may not know.
The “Contributing” section, although a little mis-placed, has very good detail on project governance, organization, rationale, design principles, etc. A good example of well done contributing docs.
Tutorial: The tutorial section gives a very conversational style walkthrough of building a simple tic-tac-toe game. This is a great intro for beginners and goes far more in-depth than the examples on the homepage. I can understand why this section is a top-level menu item, but could also see this living under Docs. In enjoy the single-page format of the Tutorial. Makes me wish the Docs were presented this way as well!
Community: Awesome content on the community page. Take lessons from this one!
Blog: The React blog is a little lack-luster. I see the appeal of having the blog embedded in the site itself, but the React community would be much better served using an existing platform like Medium to broadcast their long-form content. Is it is now, this excellent long form content is lost among the rest of the internet noise.
Wow, the first programming language (not frontend lib) site that is actually beautiful. Makes sense for a language that has received millions for its development from the European Research Council and Greylock Partners. The slick, well refined, public site shows off this enterprise ready, and well-funded, language.
Aesthetics
Modern, well organized, slick. Scala as put time into their site and given the content the care it deserves.
Information Architecture
On the home page you immediately see CTAs to download Scala, or explore the API docs. Front and center is the Scala logo and most recent stable version number. Looks very slick. The rest of the page includes project marketing copy, and effective, succinct language feature examples. Also included are upcoming events, trainings, and opportunities to connect on social media and chat — pounding home the scope of the ecosystem and support structure.
Nav: To the point: “Documentation”, “Download”, “Community”, “Libraries”, “Contribute”, “Blog”. I enjoy the extra order added by the secondary nav that appears on sub-pages.
Documentation: So many good things happening here. Love the Cheat Sheet. The landing page is welcoming and explorable, although the order of “first steps” could be more explicit, like the download page. The “Tour of Scala” is comprehensive. However, because of the density of information on this page is it very easy to be overwhelmed.
Download: Download instructions are clear, numbered and easy to read. Excellent example. Really like the 1, 2, 3 step process.
Community: Excellent overview of project structure, comms channels, etc.
Contribute: Encouraging external contribution is important enough to get a top-level nav item. Impressive. Every sub-project has a contribution guide. However, like other sections of this site, these pages are very information-dense.
API: The docs are clear and easily navigable, although could go for a UI update.
Scala Center: There is a dedicated site for the not-for-profit established to support the Scala ecosystem. It is equally well constructed and worth checking out.
Aesthetics
The Ember website, by design, has some of the most character of all sites reviewed in this article! It sets an open, everyone-is-welcome tone, and seems to say “you can get the job done *and* have fun wile you do it”! Ember treads 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.
Information Architecture
Like other frontend frameworks in this list, the Ember homepage is focused on marketing and social appeals. The only “code” on this page is the Get Started up-sell at the top. Below, there are are: Marketing blurbs with engaging illustrations, a conference ad, Ember store up-sell, and a social up-sell of “Who’s using Ember.js”. Also of note: Ember has a job board with a banner up-sell on the home page. Of all the sites reviewed on this page, Ember has some of the most slick marketing and can be used as a good example of engaging homepage material.
Nav: The nav menu contains “Learn”, “Guides”, “API”, “Community”, “Blog” and “Builds”.
Learn: The Learn page feels out of place in the nav. The page itself gives a nice overview of Ember project structure, ecosystem, etc. but may be better placed as a leaf page alongside Guides. All projects need a page like this one, but this feels haphazardly placed on the site in response to user feedback.
Guides: The Ember guides are some of the most straightforward, plain-english guides I have seen in this review. Despite Ember’s enormous API footprint, by the end of the guides you what is required for 80% of your Ember development needs. This plain-english guide with the accordion side bar is a common, and highly effective, pattern.
API: The API docs are exactly what you would expect of an autogenerated JSDoc API guide. It is the themed, attractive presentation that puts this page above and beyond most of the competition. Also of note: very few projects have a API docs version picker. This is an almost required feature for these fast-moving JavaScript frameworks.
Community: The community page kicks off with a nice hype video about how awesome the Ember community is. The page continues to describe resources for the community, bug report processes, contribution guidelines, etc. However, the most innovative feature on this page is the meetup map, a resource to help you get connected with Ember community members around the world.
Blog: This blog page feels a little more well-used than the React blog. The content is more focus on release notes and project progress reports than React’s blog which has more of a mixed bag of feature release posts and “fluff” pieces better suited for other distribution methods. Having a reliable place for reading release notes is a useful feature.
Builds: The builds page rips back the curtain of Ember’s release cycle and bares all to see. From here, you receive an excellent description of the Ember release process, what all the terminology is, and when you can expect any and all versions to land.
Footer: The Ember site has a lot of good content pushed to the site footer. This is where the links for “Team”, “Sponsors”, “Security”, “Legal”, “Logos”, and “Community Guidelines” live. These pages are important, and deserve to be surfaced in the site navigation, but are not in the 90% use cases that draw users to the site. The footer is a brilliant place for these links to live.
Aesthetics
The last visual refresh of the Ruby website was late 2013, and unfortunately it shows. Exaggerated rounded corners, subtle box shadows, and chunky buttons are echoes from a time before flat design took the world by storm. The result is a website that tastes a little stale in 2017, despite the effort put in four years prior. Beyond the slightly out-dated appearance, Ruby projects stability and professionalism with its text-heavy website, but with a dash excitement thrown in, generously brought to you by the color red.
Information Architecture
Nav: “Downloads”, “Documentation”, “Libraries”, “Community”, “News”, “Security” and “About Ruby” bring to the surface all sections of the site you may want to discover, albeit a little out of order. It feels odd to me that “About” has been relegated to the end of the list, despite it being the first item newcomers to Ruby will want to explore, and being the secondary CTA on the homepage. IMHO it should be “About Ruby”, “Documentation”, “Community”, “News”, “Downloads”. With “Libraries” and “Security” living under “Docs” and “About” respectively.
Homepage: The homepage has a beautiful hero banner, but that is about where the design effort ends on this site. The code example seems to change at random between refreshes. Below is a “latest posts” style section from the news page. This is not what I would expect to see on a major programming language’s homepage and I question the efficacy.
The Rest…: I’m not going to spend much time reviewing the other pages of the Ruby site. Beyond the homepage, it appears to be a collection lightly formatted, heavily inter-linked, markdown documents. Ruby-Lang’s writing style is casual and inviting, but not a whole lot else stands out to distinguish this site. The documentation pages largely point out to third-party resources.
Keep it simple stupid. The Rust website is bare bones. The homepage is a list of documentation resources and code examples, most linking to external sources. The primary resource “The Book” is literally a digital book with “pages” to flip through. It is a well written, step by step guide on how to become a master at rust. Be prepared to read — a lot! With a functional, clean decor, the Rust site screams “OPTIMAL”, communicating the the bare bones, to-the-metal, principles its maintainers adhere to. However, where some may call it efficient, other may call it cold and un-inviting, seeming to say: “You’re here to program, not make friends. Go read the book and come back when you have questions.”
Nav: Simple, “Documentation” (also home), “Install”, “Community”, “Contribute”.
Install: Not much to see here, just a curl command to copy and paste into your terminal.
Community: Mostly just a list of IRC channels, though also links to their blog and social accounts.
Contributing: Links to stub-page walls-of-text describing how to contribute and architecture documentation are abound.
Go
Go is the new, Google run, programming language built for fast, productive, threaded programming. There is a LOT of thought, tooling, and resources to support the Go language, and the site shows that in spades. The cluttered site is strangely somehow still reasonable to navigate for advanced users and presents information in a naturally discoverable way. However, there is a lot here, without clear site hierarchy and easy navigation, and may be intimidating to many entry level users. But, Go and its documentation does not seem to be intended for first time programmers, so despite it UI shortcomings the site accomplishes its goals.
Aesthetics
Like its sibling, Dart, Go assumes a brutalist, minimal theme. The ui appears rapidly put together, with more of a focus on volume of content presented than organization and presentation.
Information Architecture
The Go site is a very minimal, deeply linked, yet effective site. Immediately on the homepage you see a “Try Go” editable live code demo, with a list of pre-written example programs. Next you encounter the “download” button and a video explanation of the Go language. This provides a solid high-level understanding of the language, though installation of the binary could be difficult for some new developers (not the target market though).
Nav: The nav keeps it simple, with “Documentation”, “Packages”, “The Project”, “Help” and “Blog”. All go to fairly flat pages, with links that look like headers (BAD UI!). These links, go to child pages that, despite their depth and lack of context upon arriving, are surprisingly discoverable on the site.
There is a lot to discover on this site’s collection of links, so I’ll just make note of what I like.
Tour: Go has a very good interactive tour that is a wonderful introduction to the language. Could use a more advanced editor with syntax highlighting though…
Play: The “Documentation” page has a play button that pops out a Go sandbox anywhere in the site! Very cool feature.
Packages: The packages API documentation is difficult to navigate and, although all content is present, is not a pleasant experience.
Help: Great list of comms channels.
Contributors: Page is relatively hidden and deep, though very thorough. Doesn’t seem well set up for first time contributors.
Dart is the boring, suit-and-tie wearing, younger sibling of Go, ensuring stability at scale for apps of any size on any platform.
The dartlang.org site has an interesting organization, because of the distinct use-cases it tries to address. The site itself is an effective documentation of Dart the language and its features, but kicks off to specialty sites for AngularDart (for browser apps) Flow (for native apps) and Dart-vm (for server apps).
Aesthetics
Like its other sibling, Go, Dart takes a refined-brutalist, minimal theme. The ui appears rapidly put together, with more of a focus on volume of content presented than organization and presentation.
Information Architecture
Immediately, we see code. The code snippet on the homepage offers a nice annotated tour of the unique language features that make dart stand out. Below, are links out to other major project verticals that make up the Dart ecosystem. Wonderful for users looking to explore the full ecosystem, but a little confusing for those wondering where to start.
Clicking on any nav items: “Get Started”, “Language”, “Libraries”, “Tools”, “Community” take you to the same page, with the nav items revealing themselves as sections in a large secondary nav.
Getting Started: Live code demo! Wonderful way to show off and introduce the language. Below we see what, in my opinion, should be on the homepage: a flow chart of what resources to begin exploring depending on your use case. However, this is a little explicit for my taste. This flow chart should be effectively presented in the site IA instead of a “choose your own adventure” style graphic.
Language/Libraries Tour: These sections are long, stream-of-education style pages that brain dump all library features in large blocks of text, commonly linking out to generated API references for more information. Not particularly effective for early language introductions. A little more UI hierarchy may make this section more parsable.
Testing: They have a testing section! Thats exciting.
Tools: Interesting page to look at resources to spur your development.
Vue is one of the newest up-and-coming frontend frameworks out there, and the conversational, inviting nature of its website is a significant reason for its impressive adoption among industry newcomers. The project makes a point to be personal.
Aesthetics
Clean, simple, direct. All language is conversational and inviting, even the choices for nav links (ex: “Learn” instead of “Docs”) Home page is simple, inviting you to dive deeper into their, very wordy, getting started guide. The LONG dropdowns are good foreshadowing for the number of words we’re about to see scroll across the page.
Information Architecture
“Get Started” and “Github” on homepage. Vue logo is front and center, with marketing copy directly below, giving you a feel for what the framework is. Sponsors and contributors section directly below lends validity to the otherwise young framework. There is really only one place to go from here, into the primary CTA “Get Started”
The bulk of the site’s content lives under “Learn” in the nav, with four (4) sub-sections: Guide, API, Style Guide, and Examples. “Get Started” takes you to the beginning of the Guide section. All docs are versioned for every significant release.
Guide: The remainder of the guide is a very conversational, plain english explanation of every detail of the framework, with well broken-down, high-level concepts explained in approachable detail. Live code demos are interspersed, providing a very tutorial-style walkthrough.
API: Exactly what you’d expect of modern API docs. Comprehensive, type-descriptive, with links to source locations.
Style Guide: Interesting and unique addition to a learn tab. Describes best practices and common gotchyas. Very helpful for a newcomer.
Examples: A dedicated examples page shows live code examples of progressively more complex mini-apps, showing the basics of the framework, architecture best-practices, and some ways to integrate with the larger ecosystem.
The “Ecosystem” nav item is a dropdown that links out to many external (mostly github) pages for tooling recommendations, news and social pages, and other resources. Nice way to show that Vue does not live in a vacuum and provide a launchpad for those interested in getting involved..
The “Team” page contains all core and major community members, their locations, social links, core focus and ecosystem contributions.
The “Team” page is technically a sub-page on the “Meta” section of the Guides that contains a very inviting “How to get involved” section.
“Support” Section — donation links and a shop!
Angular has recently re-invented itself with a ground-up rebuild to modernize and keep up with the fast-paced world of frontend frameworks. Its latest homepage reads more like a marketing splash page, an attempt to coerce those that may be looking elsewhere in this crowded market to stick with them. Emphasizes the mature ecosystem and adoption, but is missing the personal touch! Docs strike a nice balance of detail and brevity, with multiple levels of detail depending on your needs, but power users may find themselves frustrated navigating the API docs.
Aesthetics
Very Googly, and, like any good modern Google site, it uses bold colors, large blocks, and ample whitespace to make an open and explorable site.
Architecture
Home page has once CTA: Get Started. After wading through the marketing material, theres really only one thing to do. There is no invitation to “join the community” or “contribute” here. Feels a little corporate on closer inspection.
Section for event announcements on homepage.
Nav: Contains “Features”, “Docs”, “Resources”, “Events” and “Blog”. There are no dropdowns in the nav. This removes any intimidation about the rabbit hole you are about to go down.
Features: Look! Another marketing page. Angular really wants to convince you to still use them.
Docs: The Angular docs page strikes a nice balance between friendly and professional. Opening docs page answers high-level questions like “Assumptions” (links to intro to JS resources, etc) and major launching points you may be interested in (Ex: Get a glimpse, get started, fundamentals) Launchpad for docs.
The docs section consists of progressively more in-depth (and progressively more dry) code walkthroughs.There are no dropdowns in the nav. This removes any intimidation about the rabbit hole you are about to go down. uses bold colors, large blocks, and ample whitespace to make an open and explorable site.
Docs.Tutorial: No live code demos to be had here :( But! You get a nice handhold through getting started.
Docs.Fundamentals/Techniques: Unlike the tutorial section which is a handheld walkthrough of getting started, this is a more in-depth, but still casual, explanation of features and best practices. Has a nice architecture description!
Docs.API: API docs, about as in depth as you can get. However! Theres no easy way to jump between API sections. Not quickly navigable for power-users. Some of the nicest looking API docs I’ve seen though.
Resources: Literally a list of links. Good for those interested in getting into the ecosystem a bit more, but not a very inviting.
Events: Love that theres an easy to discover events section! Great for a mature ecosystem to include.
Blog: Links to medium blog.
Swift: Apple’s newly open source language for iOS apps. The site, although it has Apple’s signature white minimalism, unfortunately feels hastily put together, with a homepage that looks like a blog post, and a long list of top-level nav items with no clear hierarchy, the site is reminiscent of an internal documentation site made public at the last minute. The site works well for experienced devs looking to get detailed information on the project, but is not structured for new developers, or those just wading into iOS development.
The “Getting Started” section is a smattering of advice on how to download (also documented elsewhere), their package manager, and debugging tools. Seems an odd, bare-bones, getting started flow.
The site does do a good job breaking down high-level project packages (ex: Compiler & stdlib, Core Lib, Package manager, etc.
Community structure, code of conduct, comms channels, etc plainly documented here.
