The Building of Jetrecord: Episode 1: The Tabula Rasa of Doom

We were out at our family cabin in Bolinas, and he was at the kitchen table close to tears, surrounded by binder paper and pencils and unopened books on birds, immobilized by the hugeness of the task ahead. Then my father sat down beside him, put his arm around my brother’s shoulder, and said, “Bird by bird, buddy. Just take it bird by bird.” –Anne Lamott

I don’t think any of us ever realizes the hugeness of the task until we sit down with our materials and attempt to make sense of it all, even though the whole making-order-out-of-chaos thing is highly overrated in my opinion. Nevertheless, that’s what I’m going to do here in this series. I’m going to take a seemingly simple task–building an online logbook for pilots–expose the underbelly, cut it apart, and then put it all together into a fantastic, cohesive product that everyone will love, including me and you and every pilot you know.

Why? Because I believe we are created to do two things: experience pain and build things. Sometimes these are one and the same. I hate to admit right from the start that this is a task to which I feel compelled, by which I feel repulsed, and about which I feel nonplussed but apparently we’re in a new age of transparency so I’m starting with me, as Michael Jackson would say. I both love and hate computers and projects. And it always happens that about the time I’ve finished a web project I’ve forgotten all about this crummy beginning stage and am strangely excited to do it all over again.

Cue film.

Download (right-click and save) QuickTime MOV (49 Mb) | QuickTime iPod MP4 (7 Mb) | QuickTime SMIL with captions (49 Mb) [Note: you must choose to open the SMIL file with QuickTime]

It Begins Like This

1. I’m building version 2 of an online logbook for pilots called Jetrecord. This is my attempt to record and share the process.
2. This is not an exercise (please place your hands inside the yellow circles); it’s the process of building a genuine application that is already live on the web. What you see here is what will be released for version 2. I’m hoping that by sharing something real you’ll be inspired to create your own projects and you’ll see what it’s like for one developer to wade through this stuff.
3. As far as sharing goes you are free to take the code, the text of this series, and the videos and reuse, repurpose, and remix them under the terms of the Creative Commons Attribution-Share Alike 3.0 United States License. More details are at the end of this post.
4. My other hope is that we can learn from each other. I am not an expert, as will become more apparent as the series goes on. Please contribute your knowledge in the comments. Can something be improved? Do you have a suggestion or a critique? I want to hear it. Please keep it constructive, though. Shuriken are not allowed.
5. If you’d like to contact me by email concerning the series, use harry@harrylove.org.

The Scope of the Series

The process of creating a web application from start to finish involves several subjects and my plan is to explore breadth rather than depth. That is, I’m going to talk about whatever will help me complete the project and I’ll mostly concentrate on the places where subjects overlap. If I don’t explain things in enough detail, I apologize. The truth is I may not know enough about a subject to explore it in depth. I’ll try to point you to the places I’m getting my information. Don’t hesitate to speak up if you’d like me to say more about a particular topic. If I have something more to say, something worth creating a new episode for, I may just do it. Otherwise, of course, I’ll point you to my sources.

Let’s Start with Questions, Goals, and Rules

I’m going to start this project the same way I would approach an essay, article, or presentation, by asking questions and then stating goals and rules. You don’t have to do it this way. This is how I do it because it works for me. I’m going to say that just once. It applies to everything I’m going to do from here on out but I don’t want to bore you to death by repeating myself every episode (there’s an important programming principle in there somewhere).

Questions

• What do I want to build?
  • I want to build a web-based logbook for pilots.
• Why do I want to build it?
  • I love aviation, data, and the connections made when data cross paths.
  • I am building this because it’s a product that I myself will use.
  • I have surveyed the available logbook software, both desktop- and web-based, and have not seen any that use the same approach to building logbooks that I’m using to build Jetrecord.
  • I believe this is a product that can work in concert with existing desktop- and web-based products.
• Is this an art project or do I need to consider my audience?
  • It’s both, but I am building this product for public consumption so I need to consider my audience.
• Who are the primary people groups in my audience?
  • Pilots
  • Air and ground crew
  • Affiliates
  • Aviation buffs
  • Their family and friends
• Do these people need this software? Why should they care?
  • Pilots must show proof to governing authorities that they have obtained any necessary knowledge and flying experience. Logbooks have been the standard method for recording flying experience for several decades.
  • The second two groups may have business concerns with the logbooks but will otherwise not need a logbook of their own.
  • The last group is important to consider because the entry of each flight will be made public, suitable for sharing with family and friends in the same way that family and friends share news, pictures, and video through blogs.
• Can I afford to build it?
  • The operating system, programming language, web framework, web server, and database server I am using are all available under open source licenses.
  • I have a computer that is well suited for the purpose of building a web application using this software.
  • I have some good software to edit the code and some to create and edit graphics for the web site.
  • The web application is currently hosted at Joyent using the $125 per month Accelerator option and there is room to grow using the current resource limits; there are both horizontal and vertical scaling options available at Joyent should the application outgrow its resources.
  • My company bank account is free but I may need to switch to a paying account if Jetrecord becomes very popular to the point of making more than a few hundred deposits per month.
  • The merchant account and credit card processing fees per month have been quoted from a reputable business at less than $50 per month.
  • The cost of doing business in Longmont, Colorado as a Sole Proprietor is a small annual fee.
  • I have access to help in preparing my taxes.
• Can I afford to maintain it and keep it running for years to come?
  • If the current ongoing fees are any indication, the answer is yes. Obviously, in the best case scenario, if Jetrecord suddenly jumps from 1,000 users to 100,000 I will need to upgrade the servers a bit. I may also need additional partners or staff to help manage the workload.
• Do I have enough domain knowledge to build it?
  • I have enough knowledge about aviation and logbooks to make a good product.
  • I have already built version 1 and it has been well received by the pilots who use it, including both general and commercial pilots.
• Do I have access to information about the domain?
  • I have access to the FAA’s regulations concerning logbooks through their web site and also via the FAR/AIM book.
  • There are many web sites, magazines, and books that focus on issues concerning pilots and aviation.
• Do I have access to customers and are they willing to teach me about the domain?
  • I have access to the current users of the product.
  • I am in contact with several pilots through Twitter and myTransponder.
  • I have spoken with several pilots over the phone who have expressed interest in helping me.

Goals

Succinctly and broadly, what is the desired end state? For example, the goal of basketball is to have more points than your opponent at the end of the allotted time for the game.

• The logbook is the key application, regardless of any related features.
• It must be as easy as possible to get data into and out of the system both from within the Jetrecord web site and from the developer API.
• It must be as useful as possible to as many classifications of pilots as possible, but focus on general and commercial aviation.

Mantra

Pilots Aren’t Robots Yet!

Rules

I’m writing some rules for myself that will serve as a guide for the decisions I make. They are written with this project in mind only.

1. Rules should help us make decisions; this is the only criteria for adding a rule.
2. Modify or discard any rules that are not helpful.
3. Use the best design principles we know how to use and spend time researching concepts we are unfamiliar with.
4. Make forward progress; no product is perfect.
5. Follow the spirit of Agile methods for software development; remember rule #2 above
6. Keep documentation in the source code except where sensitive information may compromise security or business secrets.
7. Documentation is for developers and is an interface into the system; design it well.
8. Everything should be added to the source control repository unless there is a good reason not to.
9. Code that can be extracted into a shared library (gem) or plugin should be.
10. Favor gems, plugins, other libraries, and framework code to writing our own unless there is a good reason not to.
11. Each feature must begin with a story discussing the feature and its impact, followed by sketches of APIs and GUIs, followed by test coverage, followed by implementation.
12. Metrics should be built into the project early and often.
13. Questions drive the need for answers which drive the need to record data, not the other way around.
14. Build for data access first and GUI display second.
15. Build for universal access.
16. Build for progressive enhancement.
17. Browsers must prove their worth to be included in our support; mainstream use is not proof in and of itself.
18. See also Matthew Moore’s Ruby on Rails Code Quality Checklist; remember rule #2 above

Coming Up in the Next Episode

Next I’m going to write a brief outline of the basic application. I’m also going to sketch the application on paper and make a list of parts I need to get started. I hope you’ll join me. You can subscribe to the RSS feed in order to be notified when the next episode is up. I have also created a table of contents page for this series. Until next time, cheers and happy flying.

Material You May Find Useful Related to This Episode

The Art of the Start by Guy Kawasaki

Bird by Bird by Anne Lamott

The Spirit of St. Louis by Charles Lindbergh

Building Scalable Web Sites by Cal Henderson

Getting Real by 37signals

List of software development philosophies on Wikipedia

The Building of Jetrecord by Harry Love is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. When code, text, or media in this series is not created by me and is not in the public domain I will provide links to their sources from which you can find their respective licenses and terms of use.

8 Comments

1. Episode 1 of The Building of Jetrecord : The Online Logbook for Pilots : Jetrecord spoke thusly:
   

   [...] just posted the first episode of my developer series on building version 2 of Jetrecord. If you’re interested in application development, this is for you. There’s not much [...]

   October 15th, 2008 at 9:55 am
2. Cameron Robertson spoke thusly:
   

   Harry, I am happily watch along with your v2 journey. Great questions - I think that I am going to have to run through those for my own project.

   One question though - why the Sole Proprietorship and not LLC? Still very cheap ($25) and liability protection.

   October 15th, 2008 at 10:31 am
3. Harry Love spoke thusly:
   

   When I formed Jetrecord in Seattle I created an LLC even though it was just for me. Later I was talking to some business people who said the liability protection probably wouldn’t hold up in court because I was the sole person responsible for the business. Not only that but people can still sue you personally.

   So when I formed again here in Colorado I chose to go the super easy route of sole proprietorship until I have partners. I can always reform as an LLC or a C Corp in the future if I need to. In the mean time there’s absolutely nothing to file except my taxes. I have also added some personal liability protection to my insurance coverage but it’s very small.

   October 15th, 2008 at 10:49 am
4. Grant McHerron spoke thusly:
   

   Hi Harry - it’s Grant from Australia here (Falcon124 on JetRecord :)

   Great start - I like the rules although I did raise an eyebrow at #17 - how are you defining “prove their worth”? What are the criteria of worth? (it’s not just requirements that need a valid test condition :)

   Kudos for using the CC licensing - I’m a big fan of CC licences. When I’m not trying to get myself into the air, I’m working on taking our company fully open (everything we do is CC licensed and all our projects, docs and so on are on our wiki - blog.apc.org.au and wiki.apc.org.au). Saving the world, one click at a time :)

   I’m looking forward to following your progress with this (and not just as a user of the system). I’ve been doing IT and systems development for over 20 years so hopefully I can be of some help as you move forward :)

   Cheers,

   Grant

   October 15th, 2008 at 1:34 pm
5. Harry Love spoke thusly:
   

   Right now I’m defining “must prove their worth” as “must not make me jump through too many hoops to achieve the same functionality” which I might also rewrite as “must not make me angry.” As of now, the full-featured Jetrecord web site only supports IE7+, Safari 2+, and Firefox 2+. For the new version I’m going to try to make the site content accessible and usable for most browsers and save the cool stuff for the browsers that can handle it.

   That will probably mean supporting the current list of browsers for the full-featured site, but at least older browsers will be able to get to the content.

   October 15th, 2008 at 2:26 pm
6. Grant McHerron spoke thusly:
   

   “Must not make me angry”

   Yeah - that works :)

   I still have nightmares about browser compatibility and I was *managing* the projects, not even doing the hard work on the coal face. CSS hacks to make things work the same - gotta love it.

   October 15th, 2008 at 5:51 pm
7. Noah Hendrix spoke thusly:
   

   Hey, I was thinking that you should include the ability for pilots to update their logbook using SMS or even Jott.

   Here are some links that could help, I think when you have an application that is based around something that normally takes place w/o a computer always readily accessible that it is always great to make as many gateways into the application as possible.

   Some links that I have gathered for such things include:

   This is what I like to call a Poor Man’s SMS gateway because generally the cost of maintaining SMS gateways are too extravagant for small companies to possibly afford (silly phone companies). It uses AIM and a bot to process the requests. Lifehacker has a really great example of how to implement this.

   http://lifehacker.com/software/budgetbot/hack-attack-the-aim-budgetbot-187215.php

   Of course you can go for a more traditional service (ad supported though) and use this website
   http://zeepmobile.com/

   Though perhaps not all pilots are tech savvy with the cell phone, but I bet they have a cell phone, and can make a call. For those I would suggest http://jott.com/jott/developers.html

   Of course this is all just some tips from me, but I think that you really have a place in your application for this and wouldn’t mind seeing a good rails implementation of SMS/Jott integration.

   Happy Coding :-)

   October 15th, 2008 at 11:23 pm
8. Noah Hendrix spoke thusly:
   

   Oops!! Looks like you already have that in version 1 :-( well I guess never mind!

   October 15th, 2008 at 11:26 pm

Say, say, say, what you want.

Name (required)

Email (required)

Website

Written and produced by Harry Love. Follow me with RSS. Unless stated otherwise, everything created by me is licensed CC-by-SA-3.