NUSMods:
An Inside Look

By Yang Shun / yangshun


Some content adapted from
Beng / ahbeng 's first NUSMods talk

Hi, I'm Yang Shun

I built NUSMods

(And some other things...)

What is NUSMods?

You only see the final product

Now let's take a look behind the scenes

Outline

  • NUSMods: A History
  • Application Architecture
  • Interesting Techniques
  • Dealing with Data
  • Building a Community
  • Moving Forward

What does the "Mods" in NUSMods actually stand for?

  • NUS Modules?
  • NUS Moderators?
  • NUS Modifications?
  • Officially, NUS Modifications, but any of the above works.

Goals and Objectives

  • Enhance the quality of lives of NUS students
  • Encourage students to experiment and create original community-engaging work

NUSMods Predecessors

Scratch your own itch

  • Back in 2011, the existing timetable builders weren't nice to use
  • Official timetable builder was too troublesome to use. Can't use unofficial timetable builder on Macs
  • Beng decided to solve the problem by building NUSMods as a side-project

Build something, anything

  • Building stuff is the best way to learn
  • Practice your craft
  • NUSMods was originally built to learn JavaScript properly

First version: CORSet

Don't be afraid to show your work

  • Connect with your community (NUS Hackers)
  • Friday Hacks is a great place to start
  • Everyone was a noob once

You'll never feel ready enough

(for your MVP)

  • July 6, 2012: nusmods.com registered
  • July 19, 2012: "Public" launch

MVP Tech Stack

  • Built with jQuery, Coffeescript, LESS, Jade
  • Module Dependency Management: RequireJS
  • Build process: CodeKit
  • Crawling and processing module data: Node.js

Initial flow

No one cared

How did it get traction?

Word of Mouth

  • Good things spread organically
  • Traction was mainly through word of mouth

Most well-loved feature?

The colors

Color Psychology

Pastels = calming, soothing

Summer 2014

  • Ashray and I joined the team
  • Together with Weiqing, we built Corspedia - Easily searchable CORS statistics
  • Ashray and Karan built ModMaven - Module pre-requisites tree

Summer 2014

  • Integrated Corspedia and ModMaven
  • Dedicated module pages
  • Module reviews
  • UI Refresh
    • Official NUSMods logo
    • Dark mode, theme colours

Timetable Builder v2.0

Module Finder v2.0

Module Page (NEW!)

v2.0 MVP Tech Stack

  • Backbone + Marionette, Handlebars, SASS
  • Module Dependency Management: Browserify
  • Build process: Grunt
  • Back end remained the same

Application Architecture

  • Client
    • Single Page Application
  • Server
    • No database
    • Module information and data stored as static JSON files in file directories
    • Have a look! http://api.nusmods.com

Single Page Applications

  • A webpage that is only loaded once. All necessary code - HTML, JS, CSS are retrieved in the initial page load
  • Subsequent resources are dynamically loaded and added to the page as necessary
  • Redraw parts of the UI without requiring a server roundtrip to retrieve the HTML
  • Makes use of HTML5 pushState() API to modify the URL
  • Popular SPAs that you have been using without realizing: Facebook, Gmail

SPAs: Benefits

  • Repeated HTML, CSS, JS not loaded over and over again with each new page
  • Native-like fluid experience. No page refreshes
  • Enforces decoupling of front-end and server. NUSMods v2.0 was rewritten without modifying the server at all

SPAs: Drawbacks

  • JavaScript must be enabled in the browser
  • Poor SEO
  • Unable to conduct page-driven Analytics
  • Slow speed of initial page load

Client

  • Structure generated using Yeoman
    • Scaffolds out the basic structure of a web app with a Grunt dev and build process
  • Grunt dev process
    • Watches the source code and reloads the page when file changes are detected
  • Grunt build process
    • Handlebars -> HTML
    • SASS -> CSS
    • Main CSS and JS compressed and minified into one single CSS and JS file respectively
    • Built into the dist directory for deployment

Server

  • No need for database
  • CRON job that crawls NUS pages every hour on weekdays
  • Cache the crawled HTML files in our servers
  • Provide an NUSMods API for usage by students

NUSMods API

  • Benefit NUS developers who want to build apps for students
  • Consolidate and normalizes NUS module information from:
    • CORS historical bidding statistics
    • CORS module information listings
    • IVLE API
    • NUS Bulletin
    • NUS Examination Timetable

Interesting techniques

  • Client-side Exporting
  • Themes and Colours
  • Responsive timetables

Client-side export

  • Excel, HTML and iCalendar files generated directly in-browser
  • Eliminates server round trip and can be downloaded even while offline
  • For JPG / PDF, exported HTML is rendered by server in a headless WebKit instance

Data URIs


<a href="data:application/vnd.ms-excel,%3C%3Fxml%20version%3D%221.0%22%3F
%3E%3CWorkbook%20xmlns%3D%22urn%3Aschemas-microsoft-com%3Aoffice%3A
spreadsheet%22%20xmlns%3Ass%3D%22urn%3Aschemas-microsoft-com%3Aoffice%3A
spreadsheet%22%3E…”>Excel File</a>

HTML5 Download Attribute


<a download="My NUSMods.com Timetable.xls" href="#">Excel File</a>
  • Only supported by Chrome in past 2 years, Firefox in past year
  • Downloadify library instead for other browsers (requires Flash)

SpreadsheetML

Supported since Office 2003


<?xml version="1.0"?>
<Workbook xmlns="urn:schemas-microsoft-com:office:spreadsheet"
          xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet">
  <Styles>
    <Style ss:ID="Default">
      <Alignment ss:Horizontal="Center" ss:Vertical="Center" ss:WrapText="1"/>
    </Style>
    <Style ss:ID="b">
      <Font ss:FontName="Calibri" ss:Size="12" ss:Bold="1"/>
      <NumberFormat ss:Format="0000”/>
    </Style>
  </Styles>
  <Worksheet ss:Name="My NUSMods.com Timetable">
    <Table ss:DefaultColumnWidth="35">
      <Column ss:Width="65"/>
      <Row>
        <Cell ss:Index="2" ss:MergeAcross="1" ss:StyleID="b">
          <Data ss:Type="Number">800</Data>
        </Cell>

Themes and Colours

  • Colours generated using Base16 Builder
  • Dark mode - Inspired by OS X Yosemite's dark mode
  • Change the appearance just by adding/remove classes from the <body> element

Responsive Timetables

  • Main timetable
    • Built using <table>
    • Does not fit on mobile screens
    • Not responsive
  • CSS Flex to the rescue!

CSS Flex

  •   .container {
    display: flex;
  }
  • Evenly divides and fills up free space
  •   .container {
    flex-direction: row | column;
  }
  • The direction that the flex items
    are placed in the container

Flex Timetable

Horizontal layout

Flex Timetable

Vertical layout

Making Use Of Data

Testing Assumptions

Beng's initial assumption: NUSMods' Unique Selling Proposition was the Module Finder.

(But he was dead wrong)

Listen to signs you need to pivot

  • Data doesn't lie
  • 80% of users use 20% of features
  • You need metrics

How do you know what events to capture upfront?

You don't. Just capture everything.

"Big" Data

  • We use Google Analytics to collect user behaviour
  • Google Analytics allowed for manual
    pushing of page change events
  • Log (almost) everything that the user does!

"Big" Data

Google Analytics statistics from Jan 1 to Mar 29

"Big" Data

Data tells your interesting things about your users!

Number of respective events from Jan 1 to Mar 29

Usage Trends

What do the humps represent?
Students check their timetables on Monday

Why is there a flat region at the end of February
and in the middle of March?

CNY + Recess Week, e-Learning Week

Building a Community

Engage the talented young people of NUS
to make NUSMods better (as a result, a better NUS)

Users + Developers + Reviewers

User Engagement

Mainly through Facebook and Twitter

Facebook

  • Main mode of engaging users (almost 4k likes!)
  • Push out important updates and announcements to users
  • Sacrificing aesthetics for visibility: Adding a like button to the most prominent page of NUSMods even though it adds clutter

Facebook

Constantly remind users of our existence with event posters

Facebook

Most successful Facebook post with 370 likes!

Facebook

Customer support via Facebook

Twitter

  • Not our most active account
  • Chope username @NUSMods first :P
  • We do reply to tweets mentioning NUSMods

Twitter

As useful as Google

Twitter

A PC simulation game!

Twitter

Happy users make happy developers

Developers

  • NUSMods relies heavily on developers to sustain this schoolwide service
  • A developer's best way to create value and impact to fellow students
  • NUSMods and API is all open-sourced, with the hopes of more student developers joining in
  • NUSMods Developers Hipchat channel

NUSMods Contributors

Developers Meetup

First meetup on Feb 13, 2015, when Beng came back to Singapore

Reviewers

  • In NUSMods 2.0, Disqus plugin was added to allow students
    to submit modules reviews
  • Initial phase: Manual populating of reviews database @_@
  • Literally googled for reviews of NUS modules and requested for permission to repost onto NUSMods
  • Raise awareness of ability to review modules: Module Review Contest

Module Review Contest

Contest Poster

Module Review Contest

Contest Results

Most Creative Review

Yap Zi Xuan's review for CS2100

Moving Forward

  • One-stop platform for your school-related information
  • Increased focus on user-created content:
    • NUS Whispers
    • NUS Modules Wiki
    • NUS Polls

NUSMods Collab

Other Possible Improvements

  • IVLE integrated into NUSMods
  • More colour theme customization. From Adobe Kuler maybe?
  • NUS Modules Planner

Why you should contribute to NUSMods

  • Impact the lives of 30,000 NUS students
  • Open source development is a good way to learn new things!
    • Try our new technologies
    • Code reviews from experienced peers
  • Boost portfolio as a developer
    • Increasing number of employers look at Github profile

Getting Started

Xinan

Slides: Making your first PR

Github: xinan

Bili

Slides: Getting started with contributing to NUSMods

Github: xbili

Guo Xiang

Slides: NUSMods and Tests

Github: tgxworld

Q&A

Thank You!