On building software for people

The application was a little light on tests, so I asked the other developers why they are not writing more specs? The answer was all too familiar: “it just takes forever to run them”. Yup, Rails had to load up, schema needed to be verified, the entire universe had to be included and 30 seconds later our specs were executed.

One of the largest pains when testing in Rails is the amount of time it takes to run tests. To be able to get a good flow going, test suites should run in no more than 2 seconds. However, when including Rails in your tests there’s an automatic 7 second overhead while Rails loads. A few months ago Attila Domokos and I started finding some practices to be able to run RSpec tests without Rails. He has taken that further and now runs 128 tests (including controllers and models) in less than 2 seconds. Nice work Attila!

RSpec is a great tool in the behavior driven design process of writing human readable specifictions that direct and validate the development of your application.

Jared Carroll gives us a list of practices he follows when writing tests in RSpec. One of the major advantages of RSpec over Test/Unit is the amount of work they’ve put into generating friendly documentation from your specs. Good documentation stems from understanding your code, which ultimately leads to increased trust and easier maintenance. The practices in this post give you a starting point for being able to document your app’s behavior with specs. Just make sure you run your specs with --format documentation (or add it to the .rspec file in the root of your project to make it the default).

Jeff Patton’s keynote at AgileRoots 2010 explains what he calls the “process racket”. While off-the-shelf processes like Scrum and XP can help a team get started with agile, they are only a means to an end. That end being happy users, of course. Most of these processes focus on delivery, but they don’t help us discover what our users need. Therefore, a good process needs to have a healthy balance of discovery and delivery.

We are tired of XP, Scrum, Kanban, Waterfall, and anything else getting in the way of…Programming, Motherfucker.

We are tired of being told we’re autistic idiots who need to be manipulated to work in a Forced Pair Programming chain gang without any time to be creative because none of the 10 managers on the project can do…Programming, Motherfucker.

We must destroy these methodologies that get in the way of…Programming, Motherfucker.

While I found this site very entertaining, Zed is missing an important word: it’s not just programming that’s important, it’s useful programming. And how do we do useful programming? Well, that’s what all the processes and methodologies we use are for. Without them we’re using hammers to hit screws, without realizing they’re screws.

Interestingly, Zed’s blog post on the topic is much more reasonable. Perhaps he should update the main site…

Insert mode is vi’s weakest mode. In this mode, it’s no better than any other editor, and you may as well be using any other editor. Vi’s true power lies in its ‘Normal mode’. Yes, inserting text is not normal in viland. The more time you spend in Normal mode, the more superpowers you will have. Trust me, it doesn’t get any less normal than Normal mode.

The best way I’ve found to use Vim is to enter insert mode for short bursts of typing and quickly going back to normal mode. Not only is normal mode most powerful, but I also get a more finite (and predictable) undo history.

There are two other ways to get out of insert mode:

Ctrl-[

and

Ctrl-C

I use Ctrl-C to exit insert mode. One thing I discovered is that Ctrl-C cancels any pending edits. 90% of the time this is not a problem for me. However, for that last 10%, I’ve added this to my .vimrc:

    inoremap <C-c> <ESC>

I have done a bit of Shopify development since starting densitypop. When I build Ruby on Rails apps, I can run the site locally to test my work before I commit it. Since Shopify is a hosted service, this is much more difficult. In the past I used Vision, a tool that emulates the Shopify backend through data fixtures and a server written in Ruby. It worked great until Shopify stopped updating it. Now, according to the wiki, Vision lacks a lot of features that help make development and maintainance much easier. As far as I’m concerned, it’s dead.

After that I started using “select all/copy & paste” instead. Huge pain. What I really wanted was the ability to save a file and have it automatically uploaded to my store. With the new Shopify API and Watchr this was just a small Ruby script away.

    require 'shopify_api'

    watch('(?:templates|layout|assets)/.*\.liquid') do |match|
      puts "Updating %s..." % [match[0].inspect]
      upload_template(match.to_s)
    end

    def upload_template(file)
      ShopifyAPI::Base.site =
        "http://{key}:{secret}@{domain}.myshopify.com/admin/"
      asset = ShopifyAPI::Asset.find(file)
      asset.value = File.read(file)
      asset.save
    end

(See https://gist.github.com/787359 for the latest version of this script).

Usage

1. Create a new directory for your Shopify app.
2. Create a directory called templates to store your Liquid templates.
3. Install watchr via gem install watchr.
4. Create a file called watch.rb in the root of your Shopify app.
5. Paste the above code into watch.rb. Make sure you add your API key and password.
6. Run watchr watch.rb; change a template and save it.

Voila! You can now enjoy rapid Shopify development. I may be adding some more features soon, so be sure to check back.

Caveats

This process is a very bad idea for team development. I do not recommend it if you have multiple developers working on Shopify sites. This is equally bad if you are upgrading an existing site that needs to stay public; in that case, look into setting up a test store and do the work in there. However, if you’re the sole coder this is a great way to work.

TL;DR Buy it

Recently I read Authoring eBooks by Jeremy McAnally (this is my affiliate link). This book goes through the process Jeremy used to write his books Ruby in Practice, Humble Little Ruby Book and The Rails 3 Upgrade Handbook. He starts out with picking a topic and developing a pitch to help you with marketing and focus. He then walks through how to make your book stand out amongst the sea of technical writing. After that he moves into determining who your audience is and how to write for them.

The meat of the book is on developing your content; this section is filled with some great tips such as: show don’t tell and make your examples reflect reality. He then goes into the physical process of writing: what editor to use, how to organize files and include code samples and how to stay motivated when you really don’t feel like writing. The final section talks through selling and marketing your book. He points out some companies that can help you sell your book, why you might want a publisher and how to analyze your marketing efforts to determine what’s working and what’s not.

When I read this I wasn’t sure about writing a book. I’ve spoken to a number of successful technical authors who have advised to never write a technical book for the money. Between publishers’ fees and the cost of the actual writing it’s just not worth it. Independent is scary since I wouldn’t have a sales/marketing team. Authoring eBooks makes independently publishing my own book seem much less scary, and almost possible. Not to mention, Jeremy claims to have made $40,000 on his last book in just one year. Impressive.

The best piece of advice out of this book was to really think about your idea. When I first started reading this book I thought I wanted to write a book about Git for non-developers. I’ve worked with enough designers who get on a team that uses Git and have to learn a whole new skill set. In one section Jeremy says that your idea may be obsolete before you finish your book. This made me take a step back and think about it. With all the Git UIs coming out it’s very likely by the time I finish writing, non-developers won’t need command-line Git anymore. There probably isn’t as much value in that book as I originally thought.

There are some caveats to this book. It is very short; he doesn’t delve deeply into any of the topics. It’s also not heavy on brainstorming techniques or formal writing/grammar. I would recommend looking elsewhere if you want to, for example, write a treatise on objectivist ethics. If you want to write a fiction novel this is definitely not the book for you. Check out a good book on character development and dialog instead.

So, if you’ve ever considered writing your own tech book I’d highly recommend reading this one. It’s a quick read (appx. 89 pages in ePub format) and can help you figure out if your idea is viable. Check out Authoring eBooks by Jeremy McAnally.

Update (2011-01-15): Added some caveats to the book

I said I’d update when I made my HTML5 video demo play on my iPhone. Well, today is a sweet day. Thanks to the good people at PandaStream, I was able to get it working. The key is twofold:

The video must not only be encoded H.264, but it needs a QuickTime supported container type. This works fine with FlowPlayer (the Flash player we’re using). The video’s extension must be mp4 or mov. Even with the correct encoding and container, it cannot be flv. One interesting thing to note: on the iPhone HTML5 videos do not play in-browser, but open up QuickTime instead. They do play in-browser on the iPad.

If you happen to be using PandaStream for encoding (which I highly recommend), or if you encode videos with ffmpeg and libavcodec, check Panda’s documentation for the encoder settings you need.

Oh happy day!

Steve Smith gave a great talk at Great Lakes Ruby Bash on designing code. Not MVC vs. MVP vs. insert your architecture here, but applying visual design techniques to your code. This was very poignant for me with my recent interest in learning visual design. I try to make my code as easy to look at as possible. Steve gave some extremely useful advice such as:

• Clean up other team member’s code when you have trouble following it
• Name variables and methods positively
• Avoid words like “inactive”, “not”, or “disallow”
• Always consider the user experience of your code

In my experience, the most useful technique Steve mentioned was something I like to call “code by wishful thinking”. When I start writing new code I

• Write the code as I think it should be implemented
• Stare at it for a minute or so
• Modify until the API I’ve created would make sense to someone coming in to this view the first time
• Implement the methods called from my view in models, presenters, or controller

I’m not perfect at this, but it’s a practice I try to follow when writing new code. Check out the slides from Steve’s talk and start improving the design of your code today!

Looking to do HTML5 Video on the iPhone/iPad? Here are some resources that I’ve found today that may help. I’ll admit, I still don’t have a video playing on the iPhone, but I’m working on it; and I’ll update here when I get working. In the meantime, enjoy!

• Safari HTML5 Audio and Video Guide (Official Documentation)
• Notes on HTML5 Video and iPhone (Jonathan Stark)
• Exploring HTML5 Media Elements for iPhone Safari Web Pages (Wrox Publishing)

and finally a general guide to HTML5 Video:

• Video on the Web (Dive into HTML5)