On Making Web Things

Tiny Question

2014-01-16T00:00:00+00:00

It’s mid-afternoon on day 2 of the conference. Post-lunch sluggishness is wearing off and you’re excited for the next session. You settle in, and for the next half hour watch the speaker completely nail it. Great topic, unique insights, and expertly presented. A well-deserved swell of applause.

It looks like we have five minutes for questions.

Hands shoot up in the audience. The speaker scans the room and chooses one. You give no thought to how this hand was chosen. One of the conference volunteers runs a handheld microphone over to the questioner. This eats up some time considering the size of the room, but you’re used to it. The conference last month used a standing microphone where inquiring minds hurried to queue. You also gave no thought to how that setup determined which questions were chosen.

The first question starts with some light self-promotion of the questioner’s new startup. It isn’t enough to force the conference volunteers to pull the mic away, but it is enough to make you roll your eyes. A question is eventually asked. The presenter answers. One down.

Hands up, volunteers run around, and question two begins. Except it’s actually four questions, not that the questioner says this upfront. Once the first question is answered the questioner volleys with follow-up, then another answer and follow-up. This cycle continues until the presenter graciously asks the questioner to approach them later in private so that the room can move on to more questions. You sigh and wonder if the questioner is aware of their time monopolization.

The third question isn’t a question. It’s a long, meandering, incohesive statement only tangentially related to the topic. It’s obvious that the questioner is only looking for a reaction from the presenter. Being a professional, the presenter gives their opinion despite the shaky intentions and form of the question.

Time is up. More applause. On to the next session.

We Can Do Better

Odds are if you’ve been to a conference you’ve been to that conference, sat in that session. This is the status quo for conference Q&A sessions and it is broken. Among my complaints:

Question Quality: Nobody has any idea how good a question will be until it leaves the questioner’s mouth. By the time this happens the crowd and presenter have already promised to give the question time and attention, regardless of quality. This strikes me as backwards.
Questioner Selection: In our prototypical example above, the best-case scenario when the crowd raises hands is random questioner selection. Worse yet, the speaker may select based on people they already know or by a bias, conscious or unconscious. If you use a first-come first-serve line, you’re chosing questions by who has the fastest feet and least fear of speaking in front of a crowd.
Time Management: There are probably no checks on how long it takes to ask a question. A long question may distill well into a five-second question, but what comes out at a microphone is typically a first draft. Are we surprised that first drafts are awkward, unclear, overly long, and stray off topic?
Identity: Who the questioner is and what information you would like to know about them depends on which person you are in the room. If you are a fellow attendee, you probably don’t need to know much. The question is the important part. For the presenter, the question is obviously still important but you may also be interested in connecting with the questioner later, perhaps to answer the question in more detail and provide additional resources. “Hi, my name is Questioner, I work at Company, and my question is,” does a terrible job of providing a useful identity for both parties. For the rest of the crowd it is wasted time. The presenter isn’t given a great way to connect with you again outside of a Hail Mary Google search.
Unasked Questions: Not just the raised hands that never get chosen. There are tens or hundreds of questions, great questions, locked away in the heads of those unwilling to raise their hands. Maybe they’re nervous. Maybe they think their question is stupid. We’ll never know.

Attempting to Do Better

Tiny Question is a dead simple tool designed to improve the conference Q&A experience. Here’s how it works.

The presenter logs in to Tiny Question (via Twitter) and creates a new question session.
The presenter shares the URL of this question session with the audience. This is usually done by putting the URL somewhere in the opening slides and telling the audience that there will be Q&A after the presentation, but that questions will be read from this session and not from the microphones.
Audience members who open the URL will also be asked to log in via Twitter. Once they do, they’ll be able to ask questions on the page. As others ask questions, those too will be displayed.
Audience members can upvote questions. Questions stay sorted in vote order so higher upvoted questions float to the top.
After the presentation is over, the presenter opens the question session page, sees the questions sorted by upvotes, then reads and answers them as time permits.

Let’s look at my complaints once again.

Question Quality: Questions are now seen beforehand and voted on by the crowd. High quality popular questions float to the top.
Question Selection: The idea of the presenter selecting a questioner is almost completely discarded. Selection is moved to the collective audience. The presenter does have final say on what’s answered, as they could just skip over a highly upvoted question, but the crowd will be aware of what questions were skipped, which is interesting information as well.
Time Management: Typing the question gives questioners the ability to pause, think, and self-edit questions. Presenters can also use their expertise to summarize and rephrase the question when reading it aloud.
Identity: Questions are presented next to the Twitter thumbnail of the questioner, which links to their Twitter profile. Other audience members are no longer forced to hear the short bio of every questioner. Presenters are given an identity that they can contact after the presentation for followup.
Unasked Questions: The pool of questioners is no longer limited to the outgoing and luckily chosen. There is a tradeoff though. The pool is limited to those with a Twitter profile and a connected device capable of loading a webpage. This limitation makes an argument for holding mixed sessions, where questions are fielded both on Tiny Question and live. It depends on the audience.

Like everything else on the web, this is an ongoing experiment. I hope this method can help solve some of the problems laid out above. We’ll see if it does.

Tiny Question is free for anyone to use. The source is available on GitHub should you want to create your own version of the service. Pull requests are welcome.

Ask Me Questions

Do you have a question about Tiny Question? ~~Ask it here (on Tiny Question) and I will update this post with answers.~~ Questions are closed. One more thing to note about Tiny Question: All question sessions are deleted 48 hours after creation. The tool is not meant as a permanent place for questions to live, but as an aid to a live event.

Just-In-Time Versioning

2013-11-20T00:00:00+00:00

When deck.js was published I didn’t give it a version number. The first time I did this it was an accident, or at least innocent oversight, as I was making public a project without a long-term plan. This unversioned system has lasted to this day. In place of proper versions were two branches, stable and master. Changes were made to master. When they were vetted and felt right, they were merged into stable.

It Worked for Two Years

Never in the history of the project have I received a complaint about the lack of semantic versioning. I’m inclined to chalk it up to people having the problem and not complaining, but considering that my inbox is full of complaints about every other conceivable matter I’m left to conclude that it just isn’t that important to the average user. That is… for a project like this.

When an average user consumes deck.js they download it, edit slides, tweak a theme or two, give their presentation, and then they are done. There’s no updating modules, no merging changes, no outdated plugins. Versioning never comes into play for these users. And for the power users or extension authors that rely on the core project, the fact of the matter is the API has not significantly changed in two years. In the world of semver, we’d probably be on the same minor release as day one.

But there comes a time where the API needs to become unstable, and that time is now.

1.0, 1.x, and 2.0

Deck.js version 1.0.0 is now available. 1.0 is nothing more than the current API that has existed for months (with a recent push of bug fixes.)

The important thing about a 1.0 release isn’t the 1.0 code. It’s that you have a code base against which to make minor and major changes. 2.0 means nothing without the 1.0 to compare it against. And I’m excited to work towards a 2.0. If you would like to follow along with the deck.js changes going forward from 1.0, take a look at this GitHub ticket.

This Is Not a Launch

2013-05-12T00:00:00+00:00

Two months ago I had a conversation with a potential new client over Skype. They said, “I’ve been reading through your blog posts. You mention how most people can code in the open and nobody will care, but then you allude to a mysterious new thing you’re working on without giving details. What’s up with that?”

If that sounds combative, it was not. A friendly call-out. And the best question I’ve been asked in a while. These two statements absolutely contradict each other and I intend to resolve that dissonance with this post.

Defining v1

Label it however you want — MVP, Lean, Agile — but let’s make an assumption. You want to get a minimal core product out to the public, gather feedback, and start iterating as quickly as possible. This reduces wasteful upfront work and gets you listening to your customers instead. I buy into this.

The question becomes: What features should be included day one? We could come up with a wide array of ways to evaluate the necessity of features.

Say yes/no to each feature.
Select an arbitrary number of features and cull.
Prioritize and build as many features as possible before a certain date.
Do whatever The Boss says.

But I don’t want to argue for these or any other way to evaluate features. If we accept that the waste and risk reduction of a minimal first release is good, and that fewer features minimizes that waste, the math says debating features is pointless. We should ship with zero features.¹

Well that’s obviously stupid. So let’s try it…

Announcing DeckCloud’s Launch First Feature

DeckCloud is a product with one feature: Free and Pro accounts. There’s nothing else to do. You can create an account, and you can upgrade that account to a Pro account for $9/mo. The $9 subscription gives you zero extra functionality on top of the zero existing functionality.

Great. Who cares?

Exactly. You shouldn’t care. Nobody should care about this product. Now that that’s out of the way, now that I’ve subverted the importance of the “launch”, I can start working on features and releasing them. Maybe, in time, those iterations will add up to something worthy of another human’s money.

All the Caveats

I’m not recommending everyone (or really, anyone) do this with their own apps. People have great reasons for building out a more mature app before the inititial release. But I don’t have investors paying close attention to the size and growth rate of my user base. I’m not seeking a writeup in Forbes, a front-page Hacker News link, or a viral Twitter run. I don’t need paying users right now. If these things describe you and your app, thank you for reading so long after it was obvious that this article was not aimed your way.

The Answer to the Original Question

How do you create a new product and do it in the open² in a way that nobody will care? Like this, by releasing a useless v1 and developing every feature “post-launch”. From here forward I’ll be announcing new features on the DeckCloud Blog as soon as they’re ready and not a second before. If you’re interested in keeping up with the project, subscribe or sign up for the newsletter on the DeckCloud homepage.

Ok, so zero features may be where the math leads but it’s logistically difficult. What does an app with zero features look like? A URL that resolves to a blank page? That is what DeckCloud has been for months… ↩
The DeckCloud app code will remain closed-source, but I intend to open-source as many pieces as possible. One such open-source component already exists: jquery-confirms ↩

Leave the Glasses On

2012-08-21T00:00:00+00:00

115 years ago a UC Berkeley Psychology professor named George Stratton decided to plaster a small tube to his face for a total of 21½ hours over three days. The lenses in this tube inverted his vision, turning the world upside down. Stratton theorized that with enough time the human brain could adapt to such a drastic change and function normally.

As expected, Stratton found his new spatial field difficult to navigate (emphasis mine):

All images at first appeared to be inverted; the room and all in it seemed upside down. The hands when stretched out from below into the visual field seemed to enter from above. Yet although these images were clear and definite, they did not at first seem to be real things, like the things we see in normal vision, but they seemed to be misplaced, false, or illusory images between the observer and the objects or things themselves. For the memory-images brought over from normal vision still continued to be the standard and criterion of reality. The present perceptions were for some time translated involuntarily into the language of normal vision; the present visual perceptions were used simply as signs to determine how and where the object would appear if it could be seen with restored normal vision. Things were thus seen in one way and thought of in a far different way.

The Computer Science program at Cal Poly requires students to pass CSC 430: Programming Languages I. You might think by the title that this class teaches you various programming languages. It does not. You study the anatomy of languages but use just one: Standard ML.

At the time, most coursework up to this point was written in Java or C. Standard ML is a relatively obscure functional programming language closely related to OCaml. This shift from object-oriented and imperative languages to a more functional one takes you out of your comfort zone. In C you might write a sum function for an array of integers like this:

int sum(int arr[], int length) {
  int total = 0;
  for (int i = 0; i < length; i++) {
    total += arr[i];
  }
  return total;
}

In ML you might write it:

fun sum _ [] = 0
  | sum (x::xs) = x + sum xs

Initial reactions range from frustration, to panic, to depression. You don’t know how to do the simplest things. This is one of the stated goals of the class, to throw students into the deep end of a different programming paradigm. After a couple years of navigating the noun kingdom and finally getting comfortable, you’re forced to start over.

With our knowledge and egos demolished we were tasked with a single ongoing quarter-long project: Write an interpreter. The language to interpret is D Flat, a fake stripped down subset of C#. Still, it’s a sizeable task in a new field of study using an alien language. It can be daunting.

Stratton’s preliminary attempt at his experiment left him more convinced than ever that the brain could adapt. It just needed more time. So he strapped himself in for longer, wearing his device for ~12 hours a day for eight days. After the third day he noticed some changes.

It was becoming easier to follow a line in the field of sight and, continuing the line into this larger system of things, to know what it would lead to. The rooms beyond the one I was in, together with the scene out of doors, could be represented in harmonious relation with what I was actually looking at. Such representations, however, were more or less a matter of voluntary effort…

On the fourth day:

By the fourth day the new experience had become even less trying. There was no sign of bodily discomfort, and for the first time during the experiment, when nine o’clock in the evening came I preferred to keep the glasses on, rather than sit blindfolded — which had hitherto been chosen as a welcome relief.

On day five:

When the doors were open I could walk through the entire house by visual guidance alone, without holding out my hands in front of me to warn in case of a misinterpretation of the sight-perception. For the first time, I dared to turn and sit down on a chair without beforehand assuring myself with my hands that I had placed myself aright. My movements were of course still cautious and awkward.

Day six:

Movements of the head or of the body, which shifted the field of view, seemed now to be in entire keeping with the visual changes thus produced; the motion seemed to be toward that side on which objects entered the visual field, and not toward the opposite side, as the pre-experimental representation of the movement would have required. And when, with closed eyes, I rocked in my chair, the merely represented changes in the visual field persisted with the same rhythmic variation of direction which they would have shown had I opened my eyes.

Stratton didn’t just improved his hand-eye coordination. He began internalizing this new reality.

Like so many of of my CSC peers, I had to take 430 twice¹. The second time around was still a battle, but enough of the language’s principles had seeped into my consciousness that I made it through. And while there were plenty of moments filled with pure frustration, those occasional dopamine-laden epiphanies made everything worth it.

Early in that same quarter our professor, Dr. Keen, shared with us his excitement over a language he’d been playing with during the summer. It had first-class functions, dynamic typing, and a huge install base. His enthusiasm was met with a typical mix of chuckles, eye rolls, and silent indifference as he went on to explain all the unexpectedly nice things he’d discovered about this language that was so often written off in academia: JavaScript.

Anyone coming to a new language, let alone a new family of languages, is going to face an upside down world. It’s natural. For example, newcomers to JavaScript and Node.js might butt up against:

Prototypal inheritance.
Functional variable scope and the this keyword.
Asynchronicity.
Callback pyramids.

When we hit these snags we tend to do one of three things. Allow me to stretch this metaphor a bit further.

Take the Glasses Off

You give up. You stop learning the new thing and go back to a stable reality. If that sounds condescending, know that I think this is the best option in many situations. If you need to get something done quick, that’s hardly the time to explore a new technology. Stick with what you know. Be pragmatic.

But plenty of people get to this stage, meet resistance, take the glasses off, and declare their new subject broken. Node Sucks. Ruby Sucks. NoSQL Sucks. Articles of this ilk are scattered throughout space and time, and all but a rare few are written by people that have given up at unconscious incompetence out of impatience rather than pragmatism. Try not to be this person.

Add a Second Pair of Glasses

That would certainly turn everything back upright. In Stratton’s case, it would look ridiculous, but how does it look in our JavaScript scenario? Maybe you don’t understand all these asynchronous callbacks in Node, so you start using fibers. Prototypal inheritance is confusing, so you pick up JS.Class or CoffeeScript, something with a classical inheritance syntax. Are you nesting six anonymous callbacks and hate that all your code is so far to the right? Async and step have your back.

To be clear, I am not saying that these projects are bad and should be avoided. I think CoffeeScript can be great, and I use async constantly, but we need to recognize why we’re using them. CoffeeScript is a great way to write clear, terse code and reduce the boilerplate that goes into the common patterns it abstracts away with new syntax. But using it to avoid learning how JavaScript works is a mistake. If you ever find yourself in a situation without your second pair of glasses (like say, the majority of Node modules) then you’re right back where you started, lost.

Be conscious of why you’re adding new technologies to your toolbox. Avoid doing it to cover up a fundamental knowledge gap.

Leave the Glasses On

Yes, this is the hardest path, but it’s ultimately the most rewarding. If you’re serious about mastering your craft, this is the only option. Push through and trust that your brain will adapt.

In my defense, I didn’t exactly fail the first time through. I had to bow out of all classes that quarter due to a serious illness. But in all honesty, I bet I would have failed anyway. ↩

More Upfront, Less Available

2012-06-25T00:00:00+00:00

Update: Since the original posting, the numbers I specify have changed and will continue to change. Current rates and availability will always be up-to-date on my about page.

I’ve updated my about page to included some no-nonsense information on availability and pricing. It’s a direct and transparent approach that I’ve been interested in adopting since hearing Sam Soffes discuss it¹ on The Industry Radio Show. I’m excited to make this change. Here’s what’s new:

Upfront Rate

$125/hr. $250/hr for PHP work². That’s it. Neither me nor my clients have to worry about playing the negotiation game. Instead we can focus on what services I can provide within their budget.

Minimum Commitment

20 hours minimum. This is rarely a problem, but projects big and small have overhead. I prefer to bill for coding tasks only. Four billable hours behind eight hours of project management and research quickly works against me.

Maximum weekly hours

This is the biggest change. 20 hours of work per week maximum. I’ve been working full 40+ hour weeks since October of last year. It’s time for me to pull back and start down a new path. This will give me time to focus on a product I’m developing, as well as finish some longstanding projects: Move Back to the United States™ and Get Married™.

Sam’s hire page is no longer up since he’s working on his own app, Cheddar, full time. But you can still check out the GitHub repo. ↩
This is meant to dissuade work in a technology I loathe. I picked this up from somebody on a podcast, but I can’t remember which one or who said it. If anyone knows what I’m talking about please let me know. ↩

Automating Tedium

2012-04-09T00:00:00+00:00

On a recent episode of ShopTalk Show Chris Coyier voiced his personal preference for using a suite of UI applications over running a bunch of shell commands in the terminal.

I should say that I’m not afraid of it, I just prefer most things — like I use Sass all day long, right? I don’t want to go into the terminal, cd to where my thing is, and go sass --watch and then -- and then the stupid formats and all that stuff. And then every time I restart my computer I have to open it up and do it again. I would rather use something like LiveReload or CodeKit that just automatically starts when I turn on my computer, it’s automatically watching those directories for changes. I prefer UIs.

Here’s where I’m supposed to say, “Bullshit! Learn the command line,” and then check my d20 to see if the hit was critical. Except he’s right. Doing all that stuff is annoying. Between CSS preprocessing, JavaScript transcompilation, image optimization, concatenation, minification, and source control, your average dev needs to launch a navy just to make their Hello World blink. Nobody wants to have to remember and type all this crap.

Another Option

I’m no command line junkie. Borderline competent, at best. Yet I find myself in projects that require something to happen in the command line. Spin up a node.js process. Connect to a local Mongo database. rails c. There’s no fancy omnipotent Cocoa app that will manage these things for me. The good news: I don’t even try to remember it all.

before { run 'cd ~/Sites/imakewebthings.github.com' }

tab :name => 'Jekyll' do
  run 'rvm 1.8.7'
  run 'jekyll --server'
end

tab :name => 'Sass' do
  run 'sass --style expanded --watch css:css'
end

tab :name => 'Git' do
  run 'git st'
end

run 'subl .'
run 'open http://0.0.0.0:4000'
run 'exit'

This is a Consular script. The Consular script for this blog, as a matter of fact. Consular is a terminal automator written by Arthur Chiu. You create projects which are nothing more than a Ruby file like the one above. This file defines any number of terminal tabs and the processes to run within them. From then on you can just type a few words into the command line and the whole thing is executed. No more trying to remember the tedious crap.

To install Consular:

gem install consular
Install the consular core for whatever terminal app you use. I use iTerm2 so it’s gem install consular-iterm. The project page has a list of all the supported cores and their corresponding gem names.
consular init
Open the newly created ~/.consularc file and add a require statement for your core to the top. The project page for each core will have this snippet. For iTerm it’s require 'consular/iterm'.

Now you can create projects with consular create projectname. Write the “Termfile” like the one above. Then you can launch the project with consular start projectname. Let’s take a look at that project definition from earlier, line by line, to see what it does.

before { run 'cd ~/Sites/imakewebthings.github.com' }

Anything in a before block is executed immediately and at the beginning of every new tab creation. Since I may be anywhere in the file system when I run the consular start command, I want to make sure I go to the project directory. Many terminal apps also have a default setting to go to the home directory when creating new tabs rather than keep the location from the previous tab. There are settings to change this, but it’s good to know this annoyance is out of the way regardless.

tab :name => 'Jekyll' do
  run 'rvm 1.8.7'
  run 'jekyll --server'
end

If you can believe it, tab blocks create a new tab. You don’t have to name your tabs, but I prefer it. Inside that tab I switch to ruby 1.8.7 and start up Jekyll, the static site generator that powers this blog.

tab :name => 'Sass' do
  run 'sass --style expanded --watch css:css'
end

Here is the sass watcher Chris brought up. For tabs that only have one command you don’t even need to place commands inside a block, you can just pass it the string to execute. For example: tab 'tail error.log'.

tab :name => 'Git' do
  run 'git st'
end

Runs git status just to see where things are. Since this tab doesn’t have a running process like the others, it’s also where I do any terminal work going forward. Because our original tab that everything started from is about to go away.

run 'subl .' #Opens project directory in Sublime Text 2
run 'open http://0.0.0.0:4000/blog'
run 'exit'

It is in no way a requirement of a Consular script, but if I’m using it to create tabs I run exit at the end. This closes the original tab. That original tab may be unnamed or named from a previously run script, and I no longer need or want it. Before exiting I launch anything that needs launching but doesn’t concern itself with the terminal. In this case, I open the local Jekyll instance in my default browser and open the project directory in Sublime Text 2.

Who Shouldn’t Use This

If you’re a purely front-end developer, you work on mostly static web projects, and never need to touch the shell then by all means, grab CodeKit and GitHub for Mac and be happy. This is probably your ideal setup. If you can avoid using the command line altogether, that’s awesome. But keep reading. You may have reasons for using a terminal automator beyond your development projects.

If you do everything in vim, remote pair-program, have never sullied the hair on your neck with the edge of a razor, or otherwise spend a lot of time on the command line then you want something more advanced. But if you fit this description, you already know about tmux and tmuxinator and stopped reading a long time ago.

Not Black and White

Here’s a false dichotomy for you. Either you use the UI tools or you rock the command line. Keep this from creeping into your head. These tools don’t have to be used exclusive of each other. You can easily use something like Consular to launch a bunch of apps and quit the terminal altogether. Let’s take a look at my script for Waypoints:

run "cd ~/Sites/waypoints/jquery"
run "subl ."
run "open http://local.jquery.waypoints.com/test"
run "open http://github.com/imakewebthings/jquery-waypoints/issues"
run "git st"

Aside from the git st I’m just launching applications. Two Chrome tabs and Sublime. If I didn’t use git from the command line this could just as easily end with…

run "github" # You've installed the GitHub for Mac command line tool, right?
run "exit"

I find this terminal-less ending appealing because it hints at what we’re really doing with these scripts.

Come for the Terminal Automation, Stay for the Context Switches

If there’s anything we can agree on as an industry it’s this: Context switches are bad.¹ But even in the most optimal environment — free from interrupting phone calls, hour long “design meetings”, and shoulder-perched micromanagers — there will come a time when you need to switch contexts on purpose. Let’s look at a contrived but plausible day in the life of yours truly (computer activities only):

Wake up. Check email.²
Work on Client Project.
Eat lunch. Check email.
Work on Client Project.
After dinner, fix a bug in Waypoints.
Make an improvement to a transition theme in deck.js.
Work on a draft of this blog post.
Check email.
Screw around. Facebook, games, read blogs, fantasy baseball, etc.

You know what I do when I want to work on Client Project, Waypoints, this blog, or any other coding project. But what about the other stuff? Each one of these items is a context switch, including the email and screwing around. And every time I want to switch contexts I go through the same three steps, no matter the type of task.

Quit everything. By everything I mean every visible window. When I activate Exposé/Mission Control I just see background.³
Launch iTerm2.
consular start contextname

That’s right. consular start email. consular start dickaround. Now my day turns into a series of Quit, Run Script, Do Work, Quit, Run Script, Do Work, ad infinitum. That may sound boring or robotic, but I see it as relief for the brain. I don’t need to ask myself what programs and files to open. I just need to ask myself what I should be working on right now. Then focus on doing that thing.

This probably won’t help your brain get into flow with each switch — only doing the work will get you there — but having simple repeatable steps certainly makes the transition smoother and quicker. I dare you to give it a try — start small, one or two projects at first — then try to go back. I can’t.

While they didn’t coin the phrase, perhaps the most important work on the subject of context switches and software development environments in general is Peopleware by Tom DeMarco and Timothy Lister. I was lucky enough to have a teacher who made this required reading for intro Software Engineering courses. Go read it, now. ↩
I don’t want to get sidetracked on how to do email, but these usually get answered, deleted, or tagged and filed away in 15 minutes or less. ↩
I leave the programs that live in the taskbar or dock alone, such as Adium, Twitter, and Skype. I have one windowed program that I want to keep open across all contexts, and I keep it in a separate Space/Desktop for that reason: iTunes. ↩

Moving to GitHub Pages without F❤cking Up Email

2012-03-17T00:00:00+00:00

Things look different around here. Two weeks ago I moved this site from a self-hosted WordPress install to Jekyll running on GitHub Pages. But this isn’t about the redesign or the hosting move, it’s about the three days I spent silently bouncing email afterwards.

The imakewebthings.com domain is registered through and was previously hosted on A Small Orange, which uses the cPanel site management software. My email for the site is also hosted there as part of the package. The root cause is my idiocy, but hopefully this page can provide clarity to the passing frustrated user hopelessly searching Google for answers. Here’s how it went down.

How to Move to GitHub Pages

Enough has been written on this topic over the years, so I won’t get into the details. It breaks down to:

Create a repository on GitHub with the name of username.github.com. Put your Jekyll powered site in this repository. Once you push the site will be viewable at http://username.github.com.
Add a file named CNAME to the root directory of this repository. It is a text file that just contains one line, the domain name you wish to use. In my case, imakewebthings.com.
Change the DNS settings for your domain to point to GitHub’s servers.

We’re concerned with the last step. Here are the instructions on the GitHub Pages site (emphasis mine):

Next, you’ll need to visit your domain registrar or DNS host and add a record for your domain name. For a sub-domain like www.example.com you would simply create a CNAME record pointing at charlie.github.com. If you are using a top-level domain like example.com, you must use an A record pointing to 207.97.227.245. Do not use a CNAME record with a top-level domain, it can have adverse side effects on other services like email. Many DNS services will let you set a CNAME on a TLD, even though you shouldn’t. Remember that it may take up to a full day for DNS changes to propagate, so be patient.

Sweet. I opened up cPanel to change the DNS records.

The simple DNS editor doesn’t show the A record for top-level domains, so I went to the advanced editor. The first DNS entry was an A record for the top-level pointing at my shared server IP. I changed it to point to the GitHub IP address. Several hours later the record change had started propogating and the site worked as expected. So far, perfect.

Three days later I received a Twitter DM that my email address was returning to sender with a warning, or worse, failing silently.

What Went Wrong?

The GitHub instructions don’t tell the whole story, nor should they, about all the things that could go wrong when making DNS changes. The immediate lesson: It’s perfectly possible to screw up email on a domain without switching the TLD record to a CNAME if the MX record for that domain also points to the top-level record.

Hold on, you say, What are all these different record types?

Great question, voice in my head. If you’ve managed DNS records before this is all 101 material. For folks like myself who until recently relied on other team members to deal with these matters, it’s foreign. To summarize:

A Record: The basic core of DNS. It maps a nice, pretty URL to a messy IP address behind the scenes.
CNAME: A “Canonical Name” record. It acts as an alias, redirecting lookups to another record. A common one is www.tld.com pointing to tld.com. If a user navigates to www.tld.com the DNS server will say, “Hey, go here instead.”
MX Record: This record describes where to route SMTP mail traffic. It should point to wherever your email is hosted.

If you haven’t already guessed, my MX record for the imakewebthings.com domain was pointed to imakewebthings.com which was now resolving to the GitHub IP address instead of my old shared server that hosts the email. Other hosts may point to a separate A record specifically for this purpose, but it’s worth checking. If you’re wondering why you don’t see the MX record listed, it’s because in cPanel MX records are not listed in the Advanced DNS Zone Editor. They’re in a separate page under the Mail section.

How to Fix It

Keep the top level A record pointing to GitHub’s server.
Create a new A record for mail.yourdomainhere.com. If you already have a CNAME record for the mail subdomain, change it to an A record. Point this record to your old host IP. If you don’t know it, look in the left sidebar of cPanel and click “expand stats.” It’s listed under Shared IP Address.
Change the MX entry to point to mail.yourdomainhere.com.

Give it some time to propagate. Several hours later you should start to see a steady stream of backed up messages. Congratulations. Now stop reading your email and get back to work.

Deck.js Post-mortem Quick Hits

2011-10-20T00:00:00+00:00

Two months ago marked the launch of deck.js, a jQuery framework for creating HTML presentations. The next few days followed the same path as my last open source venture: A Forrst post. Spirited discussion on Hacker News. A lot of eyes. At the time of this writing deck.js is the 37th most watched JavaScript project on GitHub.

The project has been and will continue to be an absolute blast. Things are still young and changing all the time, but here are a few of my thoughts so far:

No going back: This was my first full-on TDD/BDD project. (Waypoints tests were written post-launch.) I cannot imagine doing things any other way going forward. The benefits are immense: up-front API thrashing, reducing unnecessary MVP features, catching regressions, promoting modularity… I could go on for days. The biggest perceived “con”, increased development time, is more than erased by the time saved as a result of the pros. A project with any degree of complexity written by authors at all concerned with code quality will benefit.
Between clients: I developed deck.js off and on over the course of a few months, in lulls between stretches of client work. Yet another advantage to TDD is that it makes picking up development easier after weeks away from a project. Just fire up the tests, see what fails, and get to work. Overall, this proved to be a great way to smooth out the naturally bumpy schedule that comes with freelancing. Plus building a portfolio of decent open-source projects leads to new clients, either directly through those libraries or as part of your overall résumé.
You and I are not Marco Arment: For months after Marco opened a GitHub account it sat empty, no projects, but he had hundreds of followers. And for good reason. When you create Tumblr and Instapaper geeks are ready to look at anything you release until eternity. But you and I? Nobody is going to so much as peek at the source of our un-marketed projects. For three months deck.js lived on GitHub without any watchers. We can keep our project code out in the open, broken, miles away from anything that could be called an alpha, without worrying that anybody will use it let alone criticize it. So until you garner the gravitas of a Marco or publish public documentation and marketing material, don’t fret over revealing your source.
The project page is the project: If your open source thing falls anywhere under the umbrella of front-end web development it will be judged by the project page. When deck.js launched I made the mistake of not providing a print stylesheet for the homepage. Internet commenters deemed deck.js unprintable, despite the fact that the actual library included simplified black-and-white print styles similar to S5. This was my bad. Most people will only look at the project page and judge on that alone. It’s better to spend the time sanding the corners of your public-facing pages than try to explain to your users that they got it all wrong.

jQuery Waypoints

2011-03-02T00:00:00+00:00

Last week I pushed a little jQuery plugin to GitHub called jQuery Waypoints that gives developers an easy hook into firing a function when users scroll to any given element. Thanks to some love from the Forrst community and a brief stint in the Top 10 on Hacker News, it’s gained the attention of a few eyes. I’m just glad that somebody found it useful. Now that I’ve had a chance to process the immediate feedback and fix a bug or two, I’d like to look back on what I learned.

History

Waypoints started as a scrappy MooTools class that I wrote for a friend to use in one of his projects. The code, aside from being a little gross, had the sole purpose of snapping the user’s scroll position to the top of a section when the user scrolled close enough to it. I still don’t feel comfortable interrupting a user’s natural scroll to force them to a different one, but the concept of using scroll proximity stuck with me.

Prior Art

Remy Sharp’s inview plugin is another great way to tie user scrolling to events, but only concerns itself with two element positions: entering and leaving the viewport. If those are the only element positions you want to deal with, I still think inview is a superior plugin.

GitHub = Pleasure

This was my first real open source public project. A lot of my career agency work has been for large clients that I probably can’t even name under NDA. And my one other public repository is a MooTools port of somebody else’s original work.

Git Immersion is a great resource for anyone looking to get started using Git seriously. Anyone who has ever taken the dive will tell you: there’s no going back. Once you’re comfortable with moving between branches, committing, and pushing, GitHub Pages are cake and a natural place for project pages to live.

Documentation = Important

Considering I was 8800 miles away, I didn’t actually see it, but Kyle Neath’s Documentation is freaking awesome deck really kicked me into giving a much better project documentation experience than I might have otherwise. I probably spent as much time tweaking the wording and appearance of the docs as I did writing the plugin. Not only does it reduce friction for the developer trying to use Waypoints, it reduces friction for me in trying to answer questions and support it.

The Future

With the most recent release, I’ve finished adding core functionality. Writing unit tests, fixing bugs as they come in, and expanding the platforms the plugin covers will be the main focus in the near future. Waypoints does what it does well enough and I’d prefer to keep it light. I’ll be interested to see if anyone uses it as a brick to build something neat. If you use Waypoints and would like to share with me how you’re using it, give me a shout.

Bastard Child Selector

2010-10-25T00:00:00+00:00

The CSS child selector gets a bad rap. Most web developers rarely give it a thought and favor instead the descendant selector. But why?

What is the Child Selector?

The most simple answer: >

That’s it, the greater-than symbol. In a CSS selector it denotes a direct child and only a direct child. A selector of div > p will match all p elements that are direct children of a div element.

Contrast that with the descendant selector, represented by a space. A selector of div p matches all p elements that are descendants of div, no matter how far down the DOM tree the p exists. Maybe the p is inside an li within a ul within a section within a div? Still matches. The child selector would not.

Prior Art

Several articles have been published this year on CSS performance — how browsers read CSS selectors and render elements. Chris Coyier threw down in May with a rundown of best practices, and Jonathan Snook recently broached the subject with an explanation of why CSS doesn’t include a parent selector. The meat of these recommendations come back to a guide by Google and an aging but still relevant guide by Dave Hyatt from his Netscape days.

Read these articles, take in the lessons, and let’s look at…

An Example

Puffins

Puffins are any of three small species of auk (or alcids) in the bird genus Fratercula with a brightly coloured beak during the breeding season. These are pelagic seabirds that feed primarily by diving in the water. They breed in large colonies on coastal cliffs or offshore islands, nesting in crevices among rocks or in burrows in the soil. Two species, the Tufted Puffin and Horned Puffin, are found in the North Pacific Ocean, while the Atlantic Puffin, is found in the North Atlantic Ocean.

All puffin species have predominantly black or black and white plumage, a stocky build, and large beaks. They shed the colourful outer parts of their bills after the breeding season, leaving a smaller and duller beak. Their short wings are adapted for swimming with a flying technique under water. In the air, they beat their wings rapidly (up to 400 times per minute) in swift flight, often flying low over the ocean’s surface.

Content ripped straight from Wikipedia.

The source for the Fun Fact block might reasonably look like this:

<aside class="factoid">
  <h3>Fun Fact</h3>
  <p>The fresh heart of a puffin is eaten raw as a traditional Icelandic delicacy.</p>
  <a href="#">Learn More</a>
</aside>

And the CSS:

.factoid {
  float:left;
  width:160px;
  padding:10px;
  font-size:12px;
  background:#eee;
  margin:8px 10px 10px 0;
}
	
.factoid h3 {
  color:#c00;
  font-size:18px;
  margin:0 0 8px 0;
}
	
.factoid p {
  margin:0 0 8px 0;
}

.factoid a {
  display:block;
  margin:0;
  text-align:right;
  color:#08c;
}

From now on let’s try this: Every time you would nonchalantly write a descendant selector, instead write it as a child selector by default. A lot of the descendants we currently write could just as easily be childs, and in some of those cases you really want them to be. If after some time and thought you realize that a descendant selector is what you want, need, and intend, go ahead and change it. Here is our revised CSS:

.factoid { }
	
.factoid > h3 { }
	
.factoid > p { }

.factoid > a { }

The web development community retains the nasty habit of descendant selectors for one reason: IE6. IE7+ and every other modern browser support the child selector. While many shops out there have stopped “supporting” the ancient beast, years of ignoring the child selector have left their mark on our collective stylesheet writing standards. Changing this habit yields a few advantages.

Performance

If we focused on CSS rendering performance and rewrote our example by biblically following the Google and Mozilla articles, we would see:

<aside class="factoid">
  <h3 class="factoid-header">Fun Fact</h3>
  <p class="factoid-content">The fresh heart of a puffin is eaten raw as a traditional Icelandic delicacy.</p>
  <a class="factoid-cta" href="#">Learn More</a>
</aside>

.factoid { }
	
.factoid-header { }
	
.factoid-content { }

.factoid-cta { }

Here we have a nasty case of classitis weighing down the markup. Without going into the details of what makes classitis so heinous, let’s discard this approach.

If you read the performance articles you would know that the descendant selector will match the rightmost element, say our a in .factoid a, and look at every element up the tree looking for .factoid until it finds a match or hits the body. Using the child selector will only look one level up and stop if .factoid isn’t found. This effects more than our factoid links. The performance savings are realized for every a element in the document.

But here’s the deal: CSS performance is rarely an issue for modern websites. If you’re building a static site, the speed of modern devices and browsers will cover up the more egregious selectors. Web applications making constant and rapid DOM changes may see gains in slower handheld devices or older browsers. But there are better reasons to move towards more child selectors than just performance.

Preserving Defaults & Future Proofing

Let’s turn back to our example. Maybe we’re building this site for a client. The client swears factoids will follow this structure: Title, short sentence, link out. Done. In stone. So we write the CSS in our original form using descendant selectors, ship it and everything is dandy.

Six months later, the client decides they want to link up the word “Icelandic” to an article on Björk. And this is what they see:

Puffins

Woops.

I’ll admit, this is an elementary example, and a problem we can easily foresee, but think about the implications when applied to larger layout elements. Sure, your biggest client’s left sidebar may hold nothing but second-level navigation today, but who’s stopping it from holding a Twitter widget, two ad units, and a list of related posts down the road? In our scenario the client has assured us that a Factoid structure will not change. The more realistic scenario: Nobody is thinking about these things. They’re too concerned with how everything looks now.

How many times have you found yourself writing something like this?

a {
  color:#00c;
}

.factoid a {
  color:#c00;
}

.factoid p a {
  color:#00c;
}

Avoiding this mess — defining defaults, overriding them, and then re-overriding them again — would have once been solved by adding a class to the link. With our approach of using a child selector we avoid that extra markup cruft and preserve the defaults as we move down the DOM tree. Along with the potential performance gains, I hope this is enough to get you to move away from lazily pressing the space key and give the child selector a chance.

Extra Tidbit

The ultimate test of perfectly preserved default styles? Take all your main content and erase everything else. All the layout structure: erase it. Just leave your naked content, then apply your main stylesheet. Does it look exactly the same (fonts, margins, colors, etc.) as the in-page content, except now full width and aligned left? Congratulations. Personally, I’ve never been able to get there, but I keep aiming.

On Making Web Things

Tiny Question

We Can Do Better

Attempting to Do Better

Ask Me Questions

Just-In-Time Versioning

It Worked for Two Years

1.0, 1.x, and 2.0

This Is Not a Launch

Defining v1

Announcing DeckCloud’s Launch First Feature

All the Caveats

The Answer to the Original Question

Leave the Glasses On

Take the Glasses Off

Add a Second Pair of Glasses

Leave the Glasses On

More Upfront, Less Available

Upfront Rate

Minimum Commitment

Maximum weekly hours

Automating Tedium

Another Option

Who Shouldn’t Use This

Not Black and White

Come for the Terminal Automation, Stay for the Context Switches

Moving to GitHub Pages without F❤cking Up Email

How to Move to GitHub Pages

What Went Wrong?

How to Fix It

Deck.js Post-mortem Quick Hits

jQuery Waypoints

His­tory

Prior Art

GitHub = Pleasure

Doc­u­men­ta­tion = Important

The Future

Bastard Child Selector

What is the Child Selector?

Prior Art

An Example

Puffins

Performance

Preserving Defaults & Future Proofing

Puffins

Extra Tidbit

History

Documentation = Important