Skip to content

Instantly share code, notes, and snippets.

@peterhurford

peterhurford/open-source.md

Last active February 5, 2022 08:51
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save peterhurford/47a63d4a0fcb6c409bcf to your computer and use it in GitHub Desktop.
Save peterhurford/47a63d4a0fcb6c409bcf to your computer and use it in GitHub Desktop.
Download ZIP
What is on an open source project website?: Five case studies
Raw
open-source.md

What is on an open source project website?: Five case studies

Looking at Rails, Angular, jQuery, Prediction.io, and Redis pages to find commonalities.

Lessons Learned

  • Layout matters. A nice layout inspires trust in your project.
  • Layout is similar. All the sites had a top bar with the prominent navigation. All the main pages had introductory text.
  • GitHub Issues is used ubiquitously for bug tracking.
  • IRC seems important for communities. Gitter seems like a good choice.
  • Social proof is important. Showing testimonials, GitHub stars, download counts, other vanity metrics, etc. was common.
  • Having an easy step-by-step Hello World guide followed by more comprehensive tutorials was common and seems like a good way to get people to use the project.
  • Details about how to contribute was also common and seems like a good way to get open source contributions.

The Case Studies

Ruby on Rails

  • Layout

    • Menu bar at top with links to pages.
      • Overviwew, Download, Deploy, Bugs/Patches, Screencasts, Documentation, Community, Blog
    • Title bar
      • Logo
      • Title ("Web development that doesn't hurt.")
      • Subtitle ("Ruby on Rails® is an open-source web framework that’s optimized for programmer happiness and sustainable productivity. It lets you write beautiful code by favoring convention over configuration.")

  • Front page (Overview)

    • Tiny news bar
    • Prominent links to subpages, with pictures
      • Subselection of total pages (Get Excited => Screencasts, Get Started => Download, Get Better => Documentation, Get Involved => Community)
    • Testimonial quote from users (quotes rotate over time)
    • "Who is already on Rails?" with four companies on Rails, with pictures.

  • Download

    • Quick guide to downloading Ruby, Rails (via gem install), then creating an app (rails new). Just like 3-5 steps!

  • Deploy

    • Links out to multiple deployment options I've never heard of (e.g., Phusion, Glassfish, Warbler, Capistrano).
    • Has very small section at bottom about Heroku, which seems strange.

  • Bugs/Patches

  • Screencasts

    • Links to external screencasts (e.g., Rails for Zombies, Railscasts).

  • Documentation

    • Broken up into Guides, APIs, Books, and "why’s (poignant) guide to Ruby".
    • Guides
      • Page with a much more detailed getting started guide, showing you how to create a basic app.
      • Page explaining Active Record.
      • Much more detailed pages on Active Record, covering migrations, validations, callbacks, associations, and the query interface.
      • More pages explaining Views and Controllers.
      • Digging Deeper section with more stuff (Extensions, i18n, mailers, jobs, testing, security, debugging, command line tool, assets, JavaScript, engines, initialization, autoload, plugins, rack, generators)
      • Contributing section
      • Maintenance Policy
      • Release Notes
    • APIs
      • Getting started guide (same as really quick one in "Download")
      • Complete documentation on all the classes

  • Community

    • Mailing Lists
    • Link to people talking about Rails on Twitter
    • IRC Freenode Channel

  • Blog

    • Basically what you would expect.

Angular

  • Layout

    • Top bar
      • Logo
      • Features
      • Docs
      • About
      • Contribute
      • (at the far right) Install
      • (right below top bar) Faint social media share buttons (Google+, Twitter, Facebook, LinkedIn)
    • Title bar
      • Logo
      • Tagline: "Angular is a development platform for building mobile and desktop web applications"
      • "Learn in 5 mins" button (Quickstart)
      • Download button
    • Footer
      • Libraries - links to various Angular libraries
      • Learn - Links to Quickstart, a Step-by-Step guide, Full API Docs, Resources, and more notes.
      • Help - Links to a Google Group, a Gitter Chatroom, and the GitHub issues tracker
      • Community - Links to a blog, Google+, Twitter, and GitHub

  • Front page

    • Made of components with text on the left with links to key pages and a picture on the right
    • Advertises Features, Quickstart, and Open Source (link to GitHub)
    • Second bar
      • Advertising a conference
    • Bottom bar
      • "Loved by millions of developers"
      • "Learn in 5 mins" button again, Download button again

  • Features

    • Vaguely brags about mobile first, TypeScript (pretty cool!), integrations with other *Scripts (e.g., CoffeeScript), speed, expressiveness, routing, animations, etc.

  • Docs

    • Merely links out to Quickstart, Guide, and the API Docs. Kinda a waste of space.

  • About

    • A grid of pictures, names, and one-line descriptions of the key contributors.

  • Contribute

    • A list of Angular projects with links to their GitHub's CONTRIBUTING.md files.

  • Install / Download

    • Links to npm files for various Angular projects. Not very user friendly!

  • Quickstart ("Learn in 5 mins")

    • Pretty good guide to writing a Hello World app.

  • Step by Step Guide

    • Broken down into subpages: Getting Started, Displaying Data, User Input, Making Components
    • Guides work for JavaScript, TypeScript, and Dart
    • Getting Started -- Guide to writing a Hello World app, but more complex than Quickstart.
    • Displaying Data -- Shows you how to make the page dynamically update with new data.
    • User Input -- Shows you how to make the page dynamically update in response to user input.
    • Making Components -- Shows how an Angular app is a tree of nested components. Really quick.

  • Full API

    • Pretty standard comprehensive documentation of all the Angular functions.

  • Resources

    • Links out to external blog posts and videos explaining Angular.

  • Design Docs & Notes

    • Links to a strange, unfinished Google Drive.

jQuery

  • Layout
    • Top bar
      • Links to other projects, by logo only.
      • Links to Plugins page, Contribution page, Events page, Support page, and the jQuery Foundation page.
    • Logo
    • Menu bar
      • Links to Download page, API Documentation page, Blog, Plugins page, and the Browser support page.
      • Has a right-aligned search bar.
  • Main page
  • Bar that brags about lightweightness, CSS3 compliance, and cross-browser support. Has a very prominent download button with more subtle links to the GitHub source and how jQuery works.
  • What is jQuery?
  • Few sentences explaining jQuery.
  • right-aligned Resources
  • Links to API documentation, the jQuery Learning Center, the blog, contribution page, jQuery Foundation page, GitHub Issue Tracker, and a prominent image linking out to the try jQuery page.
  • Corporate logos
  • Links to other jQuery Foundation projects.
  • A Brief Look
    • Examples of DOM traversial, event handling, and Ajax.
  • Links to books
  • Plugins
  • Repository of all the jQuery plugins.
  • Contribute
  • Complex contribution page. Has docs on how to contribute to issues, code, the community, and the documentation.
  • Also has style guides and other conventions.
  • Events
  • Links to jQuery conferences and other events.
  • Support
    • Community support -- Links to the Learning Center, try jQuery, IRC, Forums, and Stack Overflow
    • Commercial support -- Links to two consulting companies.
  • Download
  • Links to downloading .js files for different versions of jQuery. Reasonably good instructions.
  • API
  • Standard documentation of all the functions.
  • Browser Support
  • Explanations of which versions of jQuery work on which browsers.
  • How jQuery Works
  • Various examples of jQuery.
  • Learning Center
  • Lots of complex tutorials on all sorts of jQuery-related things.
  • Try jQuery
  • The Code School class for jQuery. I did it to learn jQuery and it was quite good.

PredictionIO

  • Layout
    • Top bar
      • Logo
      • Links to About, Install & Doc, Use Cases (blog on use cases), Templates, and Support
      • Buttons to go to the Open Source Version (on GitHub) and Enterprise Edition (page about their Enterprise offerings)
    • Footer
      • Community: Download, Docs, GitHub, Support Forum, StackOverflow, Contact Us
      • Contribute: Contribute, Source Code, Bug Tracker, Contributor's Forum, Contributor Agreement, Request Features
      • Enterprise: Support, Enterprise, Services
      • Partnership: Partnership Program
      • Newsletter block
  • Main page
    • Large tagline: "Build and Deploy Machine Intelligence in a fraction of the time."
    • Smaller tagline: "PredictionIO - An open-source machine learning server for developers and data scientists to create predictive engines for production environments, with zero downtime training and deployment. Built on top of Apache Spark, HBase and Spray."
    • "What is Prediction.io?" button (links to About)
    • Social proof showing stars and forks
    • More social proof from testimonials
    • Getting started with our engine templates
      • Classification, Recommendation, eCommerce Personalization, Simple Product Discovery, and more
    • Build Predictive Engines Fast
      • Engine templates, DASE, SDKs
      • Has an image of a code sample, explanining bullets, and buttons to the following links.
      • Link to browsing engine templates
    • Unify Data for Predictive Analytics
      • Prediction.io Event Server
    • Speed Up Data Science
      • Tagline: "PredictionIO platform handles the routine work so that you can focus on solving your unique data problems."
      • Image with text showing features: model selection, accuracy evaluation, history and versioning, and parallel processing.
    • Start building cool things with PredictionIO
      • Get Started block that links to the Guide
      • Get Help block that links to the forum (Google group)
      • Get Involved block that links to GitHub and the bug tracker
  • About
    • More text explaining what Prediciton.io is
    • Link to a slideshow
    • right-aligned: "Why do developers like it?" and "Why do data scientists like it?" sections.
  • Install & Doc
    • Getting Started -- how to install
    • Integrating with Your App -- SDKs
    • Deploying an Engine -- CLIs and web services
    • Customizing an Engine -- Learning DASE
    • Collecting and Analyzing Data -- Event server and importing data
    • Choosing an Algorithm -- Built-in algorithms and how to add a custom algorithm
    • ML Tuning and Evaluation -- Hyperparameter tuning and evaluation metrics
    • System Architecture
    • Engine Template Directory
    • Demo Tutorials
    • Getting Involved -- Contributing Guides
    • Getting Help -- Links to support page
    • Resources -- Random stuff
  • Templates
    • Repository of modeling templates with pretty good documentation on each template.

Redis

  • Layout
    • Top bar
      • Logo
      • Links: Commands, Clients, Documentation, Community, Download, Support, Lisence
    • Prominent yellow bar advertising an upcoming conference
  • Main page
    • Paragraph explaining Redis, link to Read more
    • Sections
      • Try it: Link to an interactive tutorial
      • Download it: Link to downloads page
      • Quick links: Twitter, GitHub, mailing list
    • Redis news
  • Commands
    • This is the comprehensive API documentation
  • Clients
    • A list of Redis clients by programming language
  • Documentation
    • Confusingly, not the API documentation page
    • Instead, detailed tutorials about how to use Redis
  • Community
    • Mailing list, IRC, Twitter
    • Local meetups
    • Contributing Guide
  • Download
    • Stable, old, and unstable builds
  • Support
    • Community support -- points to mailing list and Freenode IRC
    • Commercial support -- points to a consulting company
  • Introduction to Redis
    • Multiple paragraphs explaining Redis, with a list of features
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment