Monday, January 27, 2014

Using Twitter for classroom queue management

Problem: 

I teach a hands-on multimedia class of 25-30 students. During lab times, the students often need help. I was finding that as I was helping one student, their neighbor would grab me as soon as I was done, and I could never get to the other side of the room.

I wanted a way to create a queue that made it fair to all students.

Constraints:


  • Students didn't need an account or access for it
  • Would always be available, so that if they were having a problem before class, they could be first in line
  • There was a mobile option, so I could check the queue while walking around the room. I didn't want to have to go back to the computer to determine who was next
  • I could get a notification if I didn't have the queue running on my machine
  • Students saw their location in the queue. 
  • It was easy, without many moving parts. This was something that I needed to stand up in a couple of hours and work reasonably well.  

Solution: Twitter as the backend


Twitter offered everything that I needed. 
  • Already managed and ordered timestamps
  • Already had access and notifications on my phone
  • Some students already had accounts, but a dev twitter account and simple custom interface would allow for anybody to access it
  • Search for the special hashtag, and the queue comes up. 
And as an added bonus, I got a chance to play with Node.js, socket.io, JQuery, jade templating, Heroku hosting and a bunch of other technologies which were new to me. 

The end result is that the students LOVE it. They recognize that it is fair, and that it is really easy for them to use at any time. 

Inspired by Google, my UI was super simple :


The tweet looks like "Drew Shefman needs help #uhmultimediaHelp @UHMultimedia 1390595370659"

  • Drew Shefman is obviously the first and last name. 
  • #uhmultimediaHelp is the hashtag that I've choosen. (University of Houston multimedia). This is ultimately my search term. 
  • @UHMultimedia is a DIFFERENT twitter account than the dev account. It is the twitter account I use for my class for announcements. I include this in the message, so that I will receive email notifications. 
  • The number at the end is the timestamp in milliseconds. I found that if a student asked for help twice, that it was not showing up a 2nd time, because twitter prevents a duplicate tweet in a short time period. 

So here is the flow: 

  1. On page load and before page display, twitter.search() for #uhmultimediaHelp
  2. Filter out  any tweets older than 5 hours (my class is only 3 hours long)
  3. Display results on page, showing name and formatted time (HH:MM)
  4. Student enters name and hits "I need help" 
  5. Socket broadcasts new entry and it gets prepended to the list element
    (this is primarily so that there is immediate feedback, and the impatient students know not to submit multiple times)
  6. twitter.updateStatus()
  7. On twitter submit success, repeat twitter.search()
  8. On search success, socket broadcasts a refresh with the resultant search list.
    (I perform this seemingly duplicate step of refresh so that if any students are using their personal twitter account, with the hashtag, they will get pulled into the queue. I decided to not use twitter.stream() api as it added a significant layer of complexity. The majority of my students opt for my interface versus using their accounts, so this is a reasonable solution for now. This decision will fail if the number of personal accounts outweighs this queue, as there is only a twitter refresh when a student submits through the queue. 
  9.  Then, starting from the bottom of the list, I can help the students in order. Woot!

Technical challenges: 


 This was my first foray into a decently complex HTML5  / Node app. So starting out *everything* seemed to be a technical challenge.  So outside of googling nearly every single line of code I was typing, here are the specific things that I ran into. 
  • I choose ntwitter as the node package to leverage for the twitter api. Unfortunately it had not been updated to Twitter's new 1.1 API. So I had to fork it, and modify it for that. You can get that version on https://github.com/dshefman/ntwitter. The change to the 1.1 was simple and you can see it at this commit
  • I tried using the twitter.stream API, but it requires a single instance. But each connection (webpage) was trying to create a new stream. After much researching, there was an idea to create two Heroku instances, one for the stream and one for the app. This was going to be too much work, so I took a different path.
  • On Heroku, I pushed up my repository without following the instructions, basically leaving out the init(). Boy it didn't like that. Basically had to delete my whole Heroku account and start over. 
  • My timezone is -5 from GMT, which is what twitter uses. Not a problem, until 7pm (my class is from 5:30 - 8:30pm). At 7pm CDT, that is 12am GMT (00:00:00), in which all of my displayed times switched to -5. It was a simple solution, but something I didn't account for when I was testing it during the day. 
  • Initially I didn't provide fast enough feedback, and the students would submit a half a dozen times before it would show up on their screen. Then they were embarrassed for submitting so much. 

Technologies Leveraged (Each was decently new to me):

  • CSS 
  • Jade templating 
  • JS
  • Jasmine BDD
  • Karma test runner (continuous mode is SUPER cool)
  • Node.js / Express
  • Socket.io
  • Twitter API via ntwitter
  • Heroku node hosting
  • JQuery

Usage example





Code:

You can find the project at:
https://github.com/dshefman/TwitterHelpQueue

There is one file missing: twitterAPICredentials.js
You will need to add your own API keys if you want to use the code.

Since I'm fairly new to all of these technologies, I gladly welcome feedback / best practices for improvement.  Thanks! 



Thursday, January 2, 2014

SCNA 2013 review



I attended Software Craftmanship North America (SCNA), this past November (2013) and wanted to share some of the major things that I got from this conference.

Software Craftmanship is a philosophy about developing software and raising the bar of the entire profession. The craftmanship manifesto augments the agile manifesto and adds that the craftsman also values well-crafted software, steadily adding value, community of professionals, and productive partnerships.

SCNA is the conference for raising the bar. It is a language / technology agnostic conference. It is a community of people who share the above values. The opening remarks of the conference are "Your annual attitude adjustment," which is absolutely true. I find the conference humbling and inspiring and everyone there cares about my growth as a developer. Thank you Twin Technologies for sending me.


The conference started with a reprimand from renown author and personal inspiration Robert Martin. His admonition was regarding the heathcare.gov debacle and how it's fallout has and will negatively effect our profession.

The take away from his presentation was regarding the "responsibility of knowing". Somewhere, some developer knew that heathcare.gov, wasn't tested and ready for production. Relating this to the Challenger explosion, Robert Martin asserts that we, professional software developers, MUST be able to stand firm when we "know" that something isn't ready.   A technology problem has now become a policy problem, where technology is preventing a legally created policy from happening. He cited some great references to the  Developer Bill of Rights and Client Bill of Rights.


Sara Gray, then presented a fantastic analogy regarding writing new worlds. Her statement is that you create the [programming] world that you live in, and are you thinking about the others (including your future self) that will have to live in that world. The analogy that she used was Harold and the Purple Crayon. You get to create your world and everything that you need, but sometimes you accidentally create monsters.

Sara asserts that like parts of a sentence, that there are parts of code. There are named things, like variable, parameters, and methods. There are pieces of knowledge, which should be extracted and then named. There are changes of state, which could be represented as "who changes state", and might be a good place for helper classes. Finally, there is the "speaking voice", which I believe is the overall flow.


Ken Auer says that you can't live on stackoverflow or github alone. The goal is to raise the bar, not win an arguments. When addressing poor code, the goal should be to raise the bar, to transfer knowledge in a constructive way, and not win the argument by proving your superior knowledge. He gave his mantra, which was "make it run, make it right, make it fast", but recognize that "make it right" is limited by the most skilled participant. Based on the Dreyfus learning models, the novice has to be "in sight" of the expert, in order for them to grow. One of the nuggets that I always look for at conferences is potential interview questions. Ken provided a good one. "What software have you shipped?"



One of the most thought provoking, and immediately applicable sessions was given by Corina Zona, entitled "Schemas for the Real World". Her assertion is that giving a form field a name or restricted answers limits its scope, and that you could declare a person invalid. People are never edge cases. Some examples would be a gender field of male/female; a sexuality field of hetero/bi/gay; drop down boxes for religion, race, or relationship status. The user often has to choose to be inauthentic to fill in these fields, saying "this isn't really me, but it is the only option". Why can't all of these fields be text inputs? What questions are we really trying to answer? Maybe the question that you are trying to answer, instead of asking for gender, ask "what pronoun do you prefer?" Based on her research, when given a free text option for gender, only 40% responded with "m, f, male, or female".


Here is another example of potential invalidation: Facebook's relationship status. Does it alienate people not in or not looking for a relationship? When does a "widowed" status change to "single"? How is the "Married, Separated, and Looking" status represented?

The cool thing about this session, was that that evening I had dinner with some college friends who work in admissions in higher education. We discussed that this was the exact thing that they *battle* with their IT group all of the time. It is very unusual to have a long lasting conversation about the things that I've learned in a conference with non-developers.

The other neat aspect of this, was that I was able to put it to use in the next form that I created. I'm organizing a parent / child dance for my daughter's school, and on the form, instead of having check boxes for mother and father, I have the following field: "Relationship of the attending adults to the child(ren)." This will hopefully give me the answers that I'm looking for... answers like "mother and father, step-father, mom1 and mom2, grandmother, etc". It provides a very rich data set.



The panel on software quality had some interesting insights. Does quality even exist? Given that it, quality, is an individual definition, it might not even be describable until you can see it or see its absence. Interestingly enough, is that quality has no value today. It has value tomorrow; it is something that you pay forward. Simplicity, which is often the sign of good quality, takes experience because it is hard. Testing is a good *tool* that might be an indicator of quality, but it is not a rule that tests mean high quality.





Dave Thomas, one of the Pragmatic Programmers,
talked about the unknown knowns and that we should teach people what we were taught, but infuse them with what we have learned. Given the matrix of what you know that you know, what you know that you don't know, what you don't know you don't know, and the what you don't know that you know; it is this last one, the unknown knowns that might be the most valuable. It is the cumulative integration of your experiences, and the critical piece which we have to try to share. A simple example to references is how do you recognize a face, or describe how you walk. Thinking about them actually breaks your ability to use the knowledge. The parts that we need to transfer, is why did you structure the code this way instead of that, or why does this code make you feel dirty?


Sandro Mancusio provided some insight into some of the criticism and rebuttal that the craftmanship movement has encountered. 

The first criticism is the "craftmanship is just XP rebranded". Craftmanship is an ideology not a methodology like XP. It is about principles not practices. Practices are chosen based on the value that they bring. 

"Craftmanship is an elitist movement." Actually, we (the crafts-people) are fully inclusive, trying to raise the bar across the industry. We recognize and support the need of novices. We NEED them for everyone to grow. 

"First crafted code, then whatever the client wants." We practice writing quality code, so that time is not a factor to deliver quality. Quality becomes inherit in our work. 

"Pragmatism over religion." The message is professionalism, it is not TDD or practices. "What does it mean to be a craftsman", is not universally definable, but a personal definition. How it is done is as important as having it done. 

One thing that struck me as particularly powerful, was his mentor's description of his first attempt at code as "disrespectful". Out of all of the adjectives available to him.... "bad, inefficient, ugly, unmaintainable", he choose disrespectful. That is quite an interesting context. 




On the nature of software development, by Ron Jefferies and Chet Hendrickson, they assert that most agile teams have it wrong. Coding is a team sport, and that everyone on the team should be somewhat capable of "scoring" even if that isn't their primary duty. Backlog refinement shouldn't be the sole job of the product owner, but a team problem-solving effort. The whole team needs the vision of the product, the "what are we building". The team is actually the product owner, and the product owner is technically the "product champion" 



Finally outside of what I've already written about, there were some notable quotes that I wanted to share. 
  • Trust-driven development. How transparent can you be to build trust? 
  • "Does my commit increase or decrease the entropy of the system?"

Oh and one last thing. I was able to participate in a code retreat at 8th Light. I'm very envious of their bookshelf.