first draft of a readme

README

@@ -1,9 +1,57 @@
-Can map states like so:
-http://chart.apis.google.com/chart?cht=t&chs=220x120&chd=t:0,100,50&chco=E2E8E4,E2E8E4,AFFF99&chld=AKALCA&chtm=usa&chf=bg,s,EAF7FE
+      ___                       ___     
+     /__/|          ___        /  /\    
+    |  |:|         /  /\      /  /:/    
+    |  |:|        /  /:/     /  /:/     
+  __|  |:|       /  /:/     /  /:/  ___ 
+ /__/\_|:|____  /  /::\    /__/:/  /  /\
+ \  \:\/:::::/ /__/:/\:\   \  \:\ /  /:/
+  \  \::/~~~~  \__\/  \:\   \  \:\  /:/ 
+   \  \:\           \  \:\   \  \:\/:/  
+    \  \:\           \__\/    \  \::/   
+     \__\/                     \__\/    
+
+
+This repository contains the unabridged source code for 
+know-thy-congressman.com, a web-service/bookmarklet that displays beaucoup
+information about your elected representatives.
 
+Let me briefly describe the nature of the beast: When you click on the KTC 
+bookmarklet, you load in all the Javascript, CSS, and Javascript Templates 
+needed to render the eventual display. A search request for the given legislator
+is sent to the server, where, if the politician's information is not yet cached
+in the database, it is split out into many different requests for each of the 
+supporting APIs, requested in parallel to a certain degree, and then merged
+back into one large JSON data dump. The politician's JSON gets cached in the 
+database, and the result is returned to the bookmarklet, which handles the 
+parsing and graphing in Javascript to display the information on the screen.
 
-YouTube
+Notable Methods:
 
-Top Words
-
-Last elected in receiving percent votes.
+  * Services.dig_up_dirt (in lib/services.rb)
+    The main API querying method. Threads out requests to each of the APIs.
+
+  * Services::Base#safe_request (in lib/services/base.rb)
+    Accepts a block that executes a request, and ensures that any momentary API 
+    downtime doesn't screw up the big picture.
+
+  * Politician#information (in app/models/politician.rb)
+    Accessing the information dump about a politician performs a search if the
+    information has gone stale.
+
+  * KTC.Loader (in public/javascripts/know-thy-congressman.js) has some 
+    interesting methods for loading cross-domain css and javascripts in a 
+    browser compatible fashion, even when JQuery has not yet been loaded.
+
+  * KTC.Grapher.visualize (in public/javascripts/know-thy-congressman.js) is a
+    messy ol' method, but is able to handle the canvas-based graphing of several 
+    types of information: earmarks, votes, and favorite words.
+
+  * KTC.Util.reloadCss (in public/javascripts/know-thy-congressman.js) is a 
+    nice debugging bookmarklet to refresh all of the CSS on the page, without
+    needing to reload it.
+
+  * KTC.Politician.INFO_TO_DISPLAY (in public/javascripts/know-thy-congressman.js)
+    is the constant that determines the layout, ordering, and data binding of
+    the final display, and makes it simple to try out different arrangements.
+
+

app/models/politician.rb

@@ -23,7 +23,7 @@ def gather_information
 
   # Is our cache empty or past its expiration date?
   def stale?
-    updated_at < 1.month.ago || json == '{}'
+    updated_at < 2.weeks.ago || json == '{}'
   end
 
 end

lib/services.rb

@@ -16,6 +16,10 @@ class NotFoundException < RuntimeError; end
 
 
   # Dig up all the dirt available about a congressman...
+  # Try to execute these calls as much in parallel as possible. However, some
+  # requests must be made before others, so take care of that as well...
+  # (eg. We need the name before looking up NYTimes tags, we need the tag before
+  # looking for NYTimes articles).
   def self.dig_up_dirt(first_name, last_name)
     data = {'search_first_name' => first_name, 'search_last_name' => last_name}
     sunlight_data, watchdog_data, flickr_data, contributor_data, industry_data, tags_data, articles_data, words_data = 

lib/services/watchdog.rb

@@ -5,9 +5,13 @@ module Watchdog
 
     URL = 'watchdog.net'
 
+    # Dig up dirt from the ever-wonderful and quite helpful Watchdog.
     def self.search(bioguide_id)
       safe_request('watchdog', :ensure => bioguide_id) do
         dog = Net::HTTP.new(URL, 80)
+        # In order to determine the real URL to request, which isn't always
+        # a straight transformation of the name, we issue a search request
+        # for the bioguide ID, and use the URL that we get redirected to instead.
         loc = dog.get("/p/search.json?bioguideid=#{bioguide_id}").header['location']
         return {} if loc.blank?
         data = get_json("#{loc}.json").first

public/javascripts/know-thy-congressman.js

@@ -485,29 +485,6 @@ KTC = {
 
     // How curvy should the curves between datapoints be?
     CURVE_FACTOR : 0.5,
-
-
-    // Test to see if the canvas is working..
-    testCanvas : function() {
-      G_vmlCanvasManager.init();
-      var width = 150; var height = 150;
-      var el = document.createElement('canvas');
-      el.id = 'some_canvas'; el.width = width; el.height = height;
-      document.body.appendChild(el);
-      var canvas = document.getElementById('some_canvas');
-      if (window.G_vmlCanvasManager) canvas = G_vmlCanvasManager.initElement(canvas);
-      var p = canvas.getContext('2d');
-      p.beginPath();
-      p.arc(75,75,50,0,Math.PI*2,true); // Outer circle
-      p.moveTo(110,75);
-      p.arc(75,75,35,0,Math.PI,false);   // Mouth (clockwise)
-      p.moveTo(65,65);
-      p.arc(60,65,5,0,Math.PI*2,true);  // Left eye
-      p.moveTo(95,65);
-      p.arc(90,65,5,0,Math.PI*2,true);  // Right eye
-      p.stroke();
-    },
-
 
     // Visualize the data provided according to the meta.
     visualize : function(meta, data) {