Here’s a link to a demonstration of the project.

I built an interactive map of Calvin College’s Hekman Library. It allows a user to add books to a map while browsing the library catalog website. This is helpful as the library layout can be confusing, even to an experienced patron. The mobile version of the website is also a handy reference for keeping track of books that you want to check out, saving you from having to write down each call number by hand on a piece of paper. While there are systems at some libraries to map individual books, I have not found a competing system that allows you to map multiple books.

Watch Bo Barg, one of my teammates, demonstrate the app:

I came up with the idea in my first computer science class in college. At the time, I was an electrical engineer, but I enjoyed the class so much that I decided to switch majors. I also, at that time, worked as a reference assistant in the library, which helped with the inspiration.

While I had thought about some of the individual problems that would need to be solved to implement such a system, I did not begin working on the project in earnest until I took the software engineering course at Calvin College in the fall of 2013. I was placed on a team of five. None of the ideas that our team discussed really excited me, so I brought up the library mapping idea and convinced the team to go ahead with it. Our team consisted of two computer science majors (including myself), two information systems majors, and a math major. I gave myself the role of front end engineer, while the other computer science major, Ryan, decided on back end engineer. The IS majors took on project management roles and the math major took on odd jobs, both in engineering and management.

The project involved a lot of learning for me. I decided to use Angular.js to build the front end, a library with which I had no prior experience. While I wouldn’t yet call myself an Angular expert, I was able to learn what I needed to in order to effectively build our app, including writing services, controllers, and directives. I decided to use Angular because it simplified our architecture to separate the server and the client, only communicating via RESTful APIs; because I had the most coding experience, so I wanted to assign myself an appropriate amount of the work; and because I wanted to learn Angular.

To render the library map graphically, I decided to use D3.js because I wanted to use resolution-independent SVGs and I was already familiar with the library. I wrote Angular directives to manipulate the SVGs, adding graphical pins to shelves and highlighting them with colors.

We simulated integrating the library catalog with our app by developing a Chrome extension to modify the library’s site. We used jQuery to scrape book information from the page and insert buttons to add and remove books from the user’s map. The buttons work by calling the API on our server.

Ryan developed the backend in Flask. We decided on this web framework because Ryan had Python experience, I had prior experience using Flask so I would be able to help him, and because I felt that it was good introductory web framework. We used pip and virtualenv to manage our dependencies.

I felt that working with the team went quite well, despite our overall lack of experience. Recognizing the limitations of our knowledge, we were able to work effectively and get help when we needed it. For the scope of our project, the work split nicely between two engineers. While we probably had more management manpower than we needed, we discovered that it was helpful to the project to let them deal with stakeholders and track our progress with burn down charts. Our fifth man, Will, was no fifth wheel either: he helped out wherever we were falling behind, getting bogged down, or just needed an exploratory scout. A major problem we had to deal with was normalizing the Library of Congress call number format used by the Hekman library. A librarian-programmer at Hekman developed a Perl script for doing just this, so we set Will to figure out how to interface the script with the rest of our Python app. While we eventually decided to go with an existing Python port of the script, his work was valuable and uncovered more issues that we would eventually need to deal with. He helped out with the Chrome extension and learned enough jQuery to write the code to scrape the book data from the library catalog web page. He also helped with spreadsheets and documentation. While his contributions code-wise to our finished product were small, he was valuable for the team because he was able to keep the project moving forward.

We discovered and fixed problems with our app through user testing. We found that users had difficulty orienting themselves on the map. At that point, the maps were rather minimalist, so I added more details to aid orientation. Another problem was that users assumed that pins on the map referred to specific locations when they were merely drawing attention to the particular row where a book was located. One way we went about solving this problem was by adding more fine-grained data so that we could pin book locations within much narrower ranges.

We had a problem with shipping. I tried to add too many features too late in the process, while doing too little to ensure reliability. We should have focused on deployment. We didn’t prioritize deployment because an ultimate goal for us was to deploy on the library’s servers. Instead, we served the website on our own laptops for testing and presentations. Unfortunately, the rush to add new features and polish on the final night before our presentations meant that we never did a complete rehearsal of our presentation. Our plan was technically elaborate as we were going to demonstrate the use of our app with a live video feed to the library (using Apple FaceTime). We didn’t discover until the presentation itself that we couldn’t easily plug into the room’s sound system and that the video stream frequently stuttered and paused. I covered with impromptu narration, but this was not the end of our troubles. Disaster struck again when I tried to demonstrate the app’s UI and found the website nonfunctional. As it turned out, the IP address for my version of the Chrome extension pointed to my teammate’s laptop (used for the live library demo) rather than my own. Everything worked prior to the presentation, but as soon as the library demo finished, they packed up their laptop and the site ceased to function. Since we hadn’t rehearsed this and didn’t have enough contingency plans, the presentation overall went poorer than it should have. I learned the importance of careful preparation and rehearsal. I also learned that it is important to have realistic ideas about what is possible to complete in a given time period. Our professor emphasized that learning to estimate time well was an important skill for a software developer and encouraged us to practice this throughout the course of the semester by asking us to predict how long each of our tasks would take and to compare our predictions with the actual time.

There is still a lot left to do on the project. We hope to add an administrative view to the app so that librarians can conveniently update shelf data as book positions shift. Ultimately, we do want to integrate our app with the library website. I also would like to open-source the tools we used to create the map so that other libraries can implement similar maps. For a project of the same size, I would probably look for a more experienced team of four, dropping one of the project managers, but keeping the interdisciplinary person. I would emphasize user testing, as I find that I always learn something new about how people use (or attempt to use) the software. I would make sure that a list of goals for the project is kept realistic and up-to-date. I would also prioritize presentation and shipping, as the project ultimately has to be sold to the stakeholders.