Jamie's Blog

The Builder

To keep the teams working as separately as possible with the least interference, we decided that the PAAL Builder, the tool used to build student schedules and lessons, would be completely HTML and Javascript. That means that there would be no server-side code, no ERB or HAML template files, and no Rails special sauce. This allowed the designers to work without developer support, and allowed developers who did not know Ruby or Rails to work solely on Javascript code. The Builder would interact with the API via ajax calls with JSON responses. A simple format for the response envelope was designed:

{
version: 0.1,
error: '',

data: {
  task: {
    id: 1,
    name: 'Brush Teeth'
  }
}
}

This is an example response upon the creation of a task with the name “Brush Teeth.” On each request, the error property would be checked to make sure that it was blank. The version property would also allow changing the API in the future without breaking the application.

In the previous post I discussed the problems of having a simple API. One common scenario is to create a task and link it with a parent task. This would happen if you wanted to create a task like “Brush Teeth” and steps underneath it like “get toothpaste,” “get toothbrush”, “brush front teeth.” Here is the code necessary to do that (I am just posting the necessary jQuery calls rather than the wrapper functions I wound up writing):

// create the task via a POST
$.post(
  '/tasks',
  taskData,
  function(envelope, textStatus, request) {
    if ( envelope.error != '' ) {
      // error
    }
    else {
      // on success, tie the newly created task
      // to a parent task
      function callbackSuccess(newTask, envelope) {
        $.post(
          '/task_parents',
          {
            task_parent: {
              task_id: newTask.id,
              task_parent_id: some_parent_id
            }
          },
          function(innerEnvelope, textStatus, request) {
            if ( innerEnvelope.error != '' ) {
              // error
            }
            else {
              // success!
            }
          },
          'json'
        );
      }

      callbackSuccess(envelope.data.task, envelope);

    }
  },
  'json'
);

Wrapper functions make this simpler to understand, but the fact that it requires two posts troubled me. Still, I avoided adding a new method to the API to do this all in one step.

When we were working on the project, the designers and another developer worked mostly on basic UI. I then worked on “installing the plumbing” as I put it, making all the API calls and using the live data. A lot of this plumbing went into the product after Give Camp. One aspect of the project I found hard after Give Camp was figuring out how a feature or UI element would work. Often, I’d be hooking up the plumbing, but be unsure of whether they wanted a stand-up shower or a bathtub. Both would get the job done, but I wasn’t sure what they had in mind, and it wasn’t clear from the design.

Part of this was due to the fact that I didn’t have the most recent design. We switched versioning systems two times during the course of Give Camp, and repository locations 3-4 times. Part of this was due to lack of notes or obvious visual stimuli. In general, after Give Camp was over, it was hard to coordinate with each other.

Thinking about the problem domain, Trevor, Sebastian, and I decided to abstract away the complexity. The problem (as I understood it then) can be explained thusly:

Students need a way to follow a list of scheduled tasks throughout the day, to assist them in performing daily activities. These tasks can be broken into more detailed tasks with steps or choices. A choice, such as what to have for lunch, is non-linear. A choice helps a student develop his sense of independence. Each choice and task may have accompanying text and audio.

Day to day within a week, the schedule of tasks may be different. Weeks can also differ from each other.

Given these simple business requirements, we decided that a step, a task, and a choice were all the same in that they had a name, audio content, text content, and that they had a parent-child relationship with each other. We decided that all of these would be “tasks” and that there would be a “task type” field to differentiate between these. The “task” paradigm yields the following definitions:

• A task is a task with linear/sequential sub-tasks
• A step is a task with no sub-tasks
• A choice is a task with non-linear, non-sequential sub-tasks

We also decided, after further discussion to make certain other things tasks. We thought that days and weeks were similar enough to a task in the parent-child relationship. We decided that

• A day is a task with linear/sequential sub-tasks whose name is a weekday
• A week is a task with day sub-tasks (days as defined above)

This allowed us to have a single Task model, and a Task Parent model, which greatly simplified the API. Instead of making REST calls to create a step, create a week, or create a choice, there would be just one create call, with a task type defining the behavior of the task. This would also make copying tasks and task trees easier, since we would only have to work with one model when doing a deep copy of a task tree.

Although this made the API really quick to build, when I started writing the builder code, interacting with the API, I found the API to be a bit low level. For example, I would have to make two calls to bind a new task to a user. First, I would have to create the task via the API, and then create the user-task relationship via the API. As I was writing nested callbacks with the jQuery ajax functions, I questioned our decision to make the API so simple. Still, I think the API is a thing of beauty, and I am still proud of what we did that weekend.

As the MECA staff were describing the application, I didn’t have a clear sense of how beneficial our work would be. To illustrate how our application would help people, they showed us a video of a student going to a gym. In the first clip, the student has trouble following directions and signage about the use of gym equipment. In the second clip, the student is following auditory prompts and exercising at the gym with little trouble.  Another student was able to prepare a meal with the help of visual prompts from a PDA. It was illuminating to see the difference that prompts could in someone’s daily life and spurred us to work even harder.

We decided to split the application into 3 components:

• A REST API written using Rails
• A HTML/Ajax builder web application
• An iPhone user application

We had a team of about eight people, and we knew we had to separate tasks somehow. There were some individuals with iPhone experience (mostly novice stuff like simple view demos), and some with Ruby experience, and then there were two designers with CSS and some jQuery experience.

We figured Trevor, who has extensive Rails experience should lead the API effort, and that Brian, who has done the most, albeit little, iPhone development using MonoTouch should lead the student application effort, while the designers should focus on designing and implementing some of the builder code. (The interface for the user application had already been worked out by group consensus.)

I decided I could best help with the API, so I worked with Trevor on that. Something that I think amazed all of us was that once we had assigned ourselves to teams and broken the project up, we functioned seamlessly, all of us entering the zone in our respective areas. It’s the kind of synergy and flow you get when the majority of your team knows their shit. It was an incredible experience to be a part of that.

We had a good framework and sample response API for the student interface and builder to start building plumbing by the time we left on Friday. Meanwhile, the iPhone app team had gotten some samples working using Monotouch. The builder interface was looking really sharp. We were off to a good start when we decided to break for the night around midnight.

In the next post, I will describe some of the insights behind the API.

Dani led us into a different conference room from the main room that most of the other conference attendees stayed in the entire weekend. We met MECA members Gloria, Kaori, and Avi who teach autistic individuals how to function independently. They discussed some of their current work and successes, including the Preparing Adolescents for Adult Life (PAAL) program.

There a number of programs that are used to make an individual’s life easier. One, used by an individual with speech impairment, is a Powerpoint presentation featuring images of common items. Clicking on an image plays a sound file that represents the image. In this way, the individual can communicate with others.

Another program is a sort of flash-card program. This program helps guide a student through daily tasks by breaking the tasks into granular steps. The program also provides a choice option that prompts the user to choose among a set number of options. Although the user program is fairly effective, the authoring application for these files is cumbersome to use. Two drawbacks of this program exist:

1. There is no monitoring component built in. Monitoring of students is done on paper.
2. There is no schedule component to the application, which would provide the students a task list of activities for the day

MECA wanted a program that not only was easy to use for students, but also a program easy to use for instructors to author lessons. Additionally, a program that incorporated a task-list and monitoring component would be especially helpful.

While the staff explained some of the requirements, we were joined by other team members: Brian, Erik, Sebastian, and then Joe. There was another person who came to help during the night but he didn’t come on subsequent days. Much of that first Friday evening was spent just gathering requirements and attempting to fully understand the problem.

When we finally thought we had enough to start, it was around eight or nine at night. In the interest of time, we decided we would not work on a monitoring component. We decided to break the remaining problem into three components:

• A REST API written using Rails
• A HTML/Ajax builder web application
• An iPhone user application

The next post will discuss the reason for this split.

Last weekend, Lisa and I took off Friday to attend Philly Give Camp. The Camp-type unconference is held to provide technical expertise and work to nonprofit groups. I first heard about the event through coworkers at Wharton, and I decided to sign up. I told some friends about it, and got Kosal and an ex-coworker from ABC, Jonathan to come as well.

I sometimes think about how great my life has been, and how fantastic it is now, and I’m disappointed in myself that I haven’t given much back. Philly Give Camp provided an opportunity to use the skills that I so love towards a noble goal. That’s one of the reasons I decided to sign up. The Give Camp was held at Microsoft’s Malvern office, where they do mostly sales, in a complex shared with other companies. There’s a fountain in the shared lobby with plenty of parking outside. In the lobby of the office, there were plush couches, along with a Guitar Hero setup. They have small offices across from their primary conference rooms that they call “Chat Rooms.”

Lisa and I went around 11AM that morning but there wasn’t much to do. We helped Dani retrieve Give Camp T-shirts from his car, and list all of the available projects on two large whiteboards. We were the first there (along with Kosal) so Dani Diaz, who organized the event, let us choose a project to work on. We chose to work on an application for Mission for Educating Children with Autism (MECA) which sounded like the most challenging project.

We had lunch at King of Prussia mall while Dani was busy shopping. When we returned, there were several developers already there. We waited for more people to arrive. Soon Trevor came, who I had met recently at Philly ETE and who I knew was a frequent attendee at Philly RB meetings. We decided to work together on the MECA project.

Our meeting with the MECA staff is described in the next post.

I just finished some blog-bling for Philly HigherEd Camp. Check them out at Get Involved.