Apple Extended keyboards – My setup

I’ve owned classic Apple mechanical keyboards for some time, but over the past few weeks I’ve been using the Apple Extended Keyboard and Apple Extended Keyboard II as my main keyboards and I really like them. They provide a lot of tactile feedback and they’re relatively quiet.

My biggest pet peeve with them has been the pesky fact that the Caps Lock key is actually a locking key. It achieves this by using a completely different Alps switch then the rest of the keyboard (the Alps SKCL Lock switch).

I am partial to swapping my Ctrl and Caps lock keys from their now-traditional positions because I use the Ctrl key all the time in keyboard shortcuts and I want it to be really accessible. Older Apple keyboards (like the M0116) have those swapped already, but those keyboards have other idiosyncracies that are impractical for common use (such as the lack of function keys, and the Esc key being where the tilde key is, and the tilde key being by the really narrow spacebar). So, I set out to customize my best Apple Extended and Apple Extended II keyboards.

Swapping the Switches

Getting the caps lock key to stop locking down is a simple matter of replacing its Alps switch with a non-locking switch. In my case I decided to swap its switch with the left Ctrl key, which I’m perfectly content never to use.

Swapping mechanical switches is easy enough; it simply requires desoldering the pins from the PCB, popping them out, and resoldering them back in. I didn’t make a video of the process but I found a great guide while browsing through resources on the MechanicalKeyboards subreddit.

This was my first time soldering so I was a bit nervous, but mechanical keyboards are an easy enough project, as the solder points are relatively large and the Apple Extended Keyboard is famously easy to get apart (just four screws and the case comes right apart). Once I got the hang of desoldering (ProTip: even if you hold the solder wick a few inches from where you touch the solder iron to it, the heat travels really far!) the hardest part proved to be prying the switches out of their original homes. I felt like I was going to break the switches, but they were sturdy. I got the new ones in their homes (they just popped right in), and soldered them together.

not bad for my first time
not bad for my first time

Key remapping

Turns out, that was the easy part. It was my hypothesis that I would just need to swap the Ctrl and Caps Lock keys in System Preferences on OS X, but there was somewhat of a catch to it. To get the computer to treat the key as an actual toggle, the keyboard is hard wired to treat any key up or key down event as both a key down plus a key up event (to prevent the computer from seeing the key as held down for a long period of time). This was problematic for using the key as a Ctrl key, because Ctrl is a modifier key, so it needs to be held down with other keys, but as soon as you pressed it down it was treated as immediately released.

I needed to use a more low-level solution and I found one in Karabiner and Seil.

A helpful soul on GitHub had the same issue as I did and did the legwork of finding a solution: remapping the Caps lock key as a Ctrl lock key.

And it worked!

I have to do some further setup to Karabiner to make this only apply to specific keyboards (I don’t want the remapping to apply to my built-in keyboard, for that one I just want to do a simple Caps Lock/Ctrl swap which can be accomplished in System Preferences).

Karabiner looks like a promising app and it already appears to have support for OS X 10.10 (plus it’s open-sourced on GitHub) so this seems like it should be a good solution for the next few years or so.

I’m really happy with the keyboards I’m using as well. I was lucky enough to snag a new old stock Apple Extended II and it has a nice springy but dampened feel, so it’s really quiet and it was totally clean so the typing motion is perfect. My Apple Extended is used but in remarkably good condition for its age, and types great too. The spacebars on each take some getting used to for me, though. I think that the stabilizing motion that the Alps based keyboards use is more resistant than what’s used in keyboards using Cherry MX switches.

Another perk of using these Apple keyboards: the Command keys are correctly mapped and are more prominently placed on the keyboard for easier reach. They’re larger than the Alt keys on a Windows-formatted keyboard as well, which makes them all the more reachable.

The Markdown Shitshow, Part Deux

So, after watching the Markdown standardization shitshow play out, some more substance is starting to come out of the woodwork.

First off, I was right in that people weren’t pissed about the name. Jeff Atwood changed the name to Common Markdown, then changed it again.

In the original renaming blog post, it was revealed that Gruber was emailed about the name Standard Markdown two weeks prior, and just never bothered to respond to that email. Instead, he approached the problem by publicly taking potshots at the project, and allegedly told Atwood that the name was “infuriating.” They tried another name, Common Markdown, but this was also a bust, and finally landed on CommonMark.

Case closed, right?

As of right now, Gruber’s still harboring ill will toward Atwood and others. It’s obvious that this isn’t about the name at all, but Gruber has yet to really articulate why; he seems to just be content to be an asshole about the project (and he invented it, so he certainly is entitled to be as big an asshole as he wants when people take his project and run with it, but I’m still calling him out on it).

Over the last couple of days, though, more context started to surface. Unfriendly exchanges between Atwood and Gruber date back many years, and there’s a great post indicating Gruber’s stance, which is essentially that he has a vendetta against standards.

That stance still wasn’t very satisfying to me. I figured there’s got to be more do it. Dr Drang posted a really solid case against what Commonmark is trying to do:

In other words, Standard Markdown isn’t a solidly built Core Markdown. Nor is it a Comprehensive Markdown with a bunch of helpful features that ol’ bastard Gruber refused to add. What it is is Yet Another Markdown Flavor, with a feature set tied to the needs of Meteor, Reddit, Stack Exchange, and GitHub. There’s nothing wrong with that, but it isn’t setting a Standard. It’s what everyone else does—some better, some worse. And in John MacFarlane’s case, he’s done it better at least three times.

Now we’re getting somewhere.

It would have been one thing if Commonmark took a hard stance and said “we’re just standardizing the core features of Markdown.” But they didn’t. They took that stance selectively, as evidenced by the GFM-inspired support for code fences, yet the lack of core support for things like tables. That seems hypocritical to me, and it’s a really valid complaint.

There are also objections to the fact that the spec was so full of really crazy edge cases and definitions of how to make the parser behave in those edge cases. After all, the spirit of Markdown is about the source being highly readable on its own pre-HTML conversion, and cases like this are are really fringe:

crazy edge case

And yes, it’s all well and good that the philosophy of Markdown is to not write weird markup, but if you want to write a robust parser for a language you don’t get the luxury of pretending edge and corner cases don’t exist. Gruber chose to write a parser that didn’t cover all these edge cases. As a Markdown user that’s not usually a big deal, but as someone who wants to write software that supports Markdown it starts to make things messy. What Commonmark created for programmers is a Markdown standard that unambiguously defines all possible input.

Here’s what I hope happens:

  • Commonmark should do one of two things: 1) drop the extras from Commonmark standard, or 2) incorporate the extras from other people’s Markdown forks to make an inclusive Markdown dialect. I personally would prefer the latter, assuming that the standard allows for a lot of flexibility on these extras. I personally love how Pandoc supports four ways to make tables
  • Gruber moves on and stops bringing it up, and either participates in the Commonmark community to help shape it, or follows his current strategy of being happy with what he initially created and sticking with that.
  • Commonmark becomes a de facto standard for Markdown formats, and when people are building their own Markdown forks, start off using Commonmark as their baseline, and extend from there.

Standard Markdown

update: the name’s been changed to Common Markdown

Yesterday, Jeff Atwood announced that Standard Markdown, a project he had been working on for some time, was finally completed and ready for public review.

Like many a Markdown enthusiast, I have struggled with the fact that Markdown doesn’t have a standard. It does have an ambiguous definition which is a nice plain English way of describing how to use it, and it does have a reference implementation in Perl which people have leaned on as an official spec, but it too has ambiguities and bugs, and given that it hasn’t been touched in over ten years as of the time of this post’s writing, it’s safe to say that John Gruber (the co-creator of Markdown) has no interest in maintaining a spec for Markdown that is of the caliber needed for how widely it’s used, aside from a few fleeting mentions of his own preferences in some discussion boards.

I’m not upset that Gruber has left it untouched; I’m really happy that he and Aaron Swartz created it, but its situation has left us with some issues which Jeff Atwood has described in great detail, and Jeff Atwood set out to solve it by creating Standard Markdown.

The intent is misrepresented:

Jeff Atwood isn’t just going around being pissed that Markdown got abandoned from the top. He actually took the initiative to go about building a canonical standard, and he did in about as much the right way as a person can. He got together major players who are using Markdown in a big way (and often slight dialects of it), each with varying uses of Markdown (some using it for documentation like GitHub, others using it in forum software, etc.), and these companies worked together to build a solid standard of Markdown that everyone can work from, complete with a reference C and JavaScript implementation. There is now a detailed and unambiguous Markdown spec that sets rules on things that were previously unclear and deviates as little as possible from standard Markdown (and it doesn’t deviate from any of the major things you come to expect from any Markdown implementation).

Gruber’s reaction:

(this is @markdown’s second tweet in this account, the first is from several years ago describing Markdown)

A lot of people are taking the “I just hate that they called it that” stance:

That seems like an easy shot to take at Standard Markdown (easier than saying it was taken over, because Gruber has mostly stopped maintaining it). People are treating it as though this is some attempt to mislead people into thinking that Standard Markdown is the original Markdown.

Yes, the intent is absolutely there that Standard Markdown become the canonical Markdown, and it probably will become the de facto Markdown, because there’s so much weight behind it. The creators don’t see this as another fork of Markdown; we have plenty of well-defined forks and forks of forks (for instance: Pivotal Tracker made their own implementation of Markdown in the new Tracker, and described as a slight variant to GitHub Flavored Markdown).

Gruber is fully credited throughout Markdown’s spec, and great care was taken to make sure the spirit of Markdown is well-respected (after all, that’s what draws us to it). If you want to go and see Gruber’s spec in all its ambiguous glory, you can do so. There’s a link to it in the second paragraph of the home page of Standard Markdown’s site. Standard Markdown as a proper noun is a decent enough name. Already googling “standard markdown” will get you links to Atwood’s group’s implementation on the first page of results, and the name “standard markdown” is distinct from just plain old “Markdown” to indicate there is some standard to be followed.

I struggle to believe Gruber’s in all this fuss because of a name. Is Gruber upset he wasn’t consulted? He didn’t express interest in solidifying the spec when Atwood was lamenting the fragmentation of Markdown. If he had shown any interest in being involved in making a canonical unambiguous spec, it doesn’t seem like he would have been denied that opportunity. And even in the absence of his participation, his opinions were consulted in making the spec; there are links to his comments in there.

Is there worry that Markdown is being taken over by a consortium that might later grow to not represent users’ interests later on? I admit that worries me, but standards like Markdown shouldn’t evolve much (less so with a general-purpose canonical spec), and when they do, they should do so slowly and with discussion by stakeholders, exactly the type of thing a standards body solves. If new use cases emerge and Markdown isn’t adequate, people can adopt something new. And since Markdown is just plain text, no one’s ever really in danger of their data becoming inaccessible through Markdown falling out of favor.

Are people upset at specific design choices made about Standard Markdown? Are any of the changes breaking to the point where so-called Standard Markdown looks nothing like Markdown? None of the people in my Twitter feed mention that, and if they had, I’d consider those legitimate complaints, especially if this is to become a more widely adopted Markdown spec. And if they did have such concerns, that’s what the discussion site is for. But the people I’m seeing complain about Standard Markdown aren’t complaining about this.

Being upset that it’s named “Standard Markdown” is just petty. Standard Markdown is the result of a huge amount of work, and by taking a giant undertaking and redirecting all the attention onto its name it’s a slap in the face to the effort that people put into Standard Markdown in good faith to make it a better language. It feels like when Richard Stallman tried to insist that people refer to Linux as GNU/Linux. Maybe he was right and had the moral high ground, but it wasn’t a pragmatic choice.

John, if you’re reading this, Standard Markdown is the best thing to happen to your markup language since you invented it ten years ago. It’s too widely used for your original Markdown spec to be adequate for all use cases, and people stepped in and built a thorough spec and reference implementations. Something like this ensures the long-term health of Markdown, and what it needs above all is a thumbs-up from you, not quibbling over the name of the standard. I hope you review the standard and provide feedback and guidance on it. It would be sad if you became a footnote in Markdown’s history over something so minor as what a spec is named.

Amazon’s e-book hubris

Amazon’s starting to play some hardball negotiation with Hachette, and it’s got Amazon’s critics worried. They envision this drab world where the only way to enjoy a book is on Amazon’s terms. 

People have formed this impression that because Amazon is by far the leader in selling e-books, that they somehow have consumers in some sort of death grip, unable to migrate out of Amazon’s ecosystem.

But Amazon’s really not in some insanely advantageous position. Amazon currently sells the most eBooks, but there’s not an incredible barrier to entry to opening an e-book shop. In fact, I buy almost all my books from independent publishers (mostly because they cater to my demand for DRM-free PDFs on technical topics). 
If Hachette really wanted to, they could just tell Amazon to fuck off and sell all their books on the many other stores out there. It’s true that Amazon is pretty much the only game in town if you want to sell a DRM-wrapped book (iBooks is a probably distant second), but Hachette is perfectly free to just not sell their books with DRM. And as soon as publishers realize that letting Amazon call the shots is too high a price to pay to have DRM in your books, they’ll give up on requiring some asinine copy-protection scheme in their digital books.
Of course, Amazon is world’s most popular bookstore, but is that really that valuable? Being in the world’s largest bookstore just means your books intrinsically are just another face in the crowd. Is someone really just going to give up after they don’t see your book in Amazon’s results, or are they just going to Google your book’s title and find that they can grab it from somewhere else?
People could still read your books on Kindles; the MOBI format is an open standard and Kindles will open them. 
If enough publishers started selling DRM-free, a bunch of other e-reader vendors could come along and offer alternative devices to Kindle, even ones that offer Whispersync-like features but without the restriction that it only works with stuff you bought from an official store. 
So let Amazon keep selling you books at a loss. They’ll never achieve a monopoly position where they can excessively mark up book prices in the long run; a competitor would just come along and undersell them.
This is a potentially bright future for publishers. Whereas publishers were starting to look like useless middle men in a world where the internet makes publishing a book pretty easy, a proliferation of new eBookstores means a publisher now has a legit way to earn its keep (in addition to doing other really useful things like editing and marketing).
This is a potentially bright future for people who love books, too. I buy DRM-free almost exclusively because I want to truly own my books. I want to open my books in whatever app I choose, on whatever device I choose, and back them up however I choose, and even lend to friends however I choose. 

You won’t believe this blogger’s New Year’s Resolution

I’m done clicking links to Upworthy and similar linkbait-y sites that show up in my Facebook feed, and I think you should too.

Usually the links are mildly interesting, but sites like these aggressively A/B test different techniques for titling them to end up with this exaggerated, sensationalized title. The link title, instead of being a helpful description of what I’m about to click on, has no real bearing on the actual content. The link is just desperate and will do anything to get my click.

This comes off as such a first world problem, but it really bothers me how disingenuous these sites are, stopping at nothing just to drive page views. It’s the internet equivalent of tabloid magazines at the checkout line, and I think we should expect better.

Review: Remote: Office Not Required

37signals released their long-awaited third book today to much fanfare. 

It’s an incredibly quick read. My biggest worry was that it was going to be another Rework, which basically was a manifesto that talked up how 37signals works and it conveniently points to 37signals as an example of success. Rework often would point to a couple of big companies as well and say “hey, they did it  too!”

Remote doesn’t speak in (quite) so many platitudes. A good chunk of the book is dedicated to selling you on remote work and giving good rebuttals to the common arguments people have against remote work, but it actually dives into the “how” of implementing a remote work culture as well.

It doesn’t dive too deeply into the nitty gritty details (and for something this general, you really can’t) but it talks enough about the pitfalls that if you read through this you’ll have a good understanding of what to expect going in.

It’s worth the less than two hours it’ll take you to read and I think 37signals has a really great vision of what a workplace can be. Check it out! 

Buy on Amazon

[I have no affiliation with these guys and I don’t get anything if you click that link and buy it]

Don’t make perfect modularity the enemy of a good refactor

I often find myself reviewing pull requests and I will find classes that contain a lot of domain-specific logic that aren’t relevant to the class itself. I’ll point it out and the response is often “I plan to extract this out into a gem, but I just haven’t had a chance/I’ve been busy.”

Extracting the functionality out into a gem would be great, but I’ll be the first to admit that’s the kind of task I’d procrastinate to no end. You have to extract the functionality, get the right directory structure, get a gemspec in place, then you have to host the gem on Rubygems or if you gem is private, Gemfury. Even then, when you make changes to the gem you have to go and do a Bundler update on the apps that use the gem.

Don’t start with that solution, though. Start by extracting the out of place functionality into a new class that just lives inside the /lib directory in the application. In Rails apps, everything in /lib is already included so you can really just extract the code into the new class file and you’re ready to go.

You probably feel like you could do better than that, and that’s a great attitude you have, but by extracting functionality into a new class and out of the unrelated class, you just addressed the biggest concern, and if in the future you find that you really do need a gem (for instance, maybe you’ve got other apps that need the functionality in that class) you’ve already got the class and a unit test file (right? right?) separated out to easily slip into a gem.

It was a Friday

It was a Friday, and I was in second grade. I got up that morning eighteen years ago, had breakfast, and my brother and I went to catch the bus. 

It’s interesting how many school days I’ve been through and I don’t remember what went on in many of them, but I remember that on this day, we had art class and I completed a project (a paper bird stuffed with cotton – side note: my art skills were not any better back then). Our class took a walk out onto a trail to observe some of the natural wildlife there. In science class we had been learning about the eye and I was looking forward to our school nurse bringing cow eyes for us to dissect the next week.

That afternoon, I was taking a spelling test and I was 17 words in out of 20 when the secretary said my dad was there to pick me up. My teacher, impatient, asked if I could finish the test but that wasn’t an option; I’d have to make it up later. We met my dad and his work colleague who drove me and my brother home in his van.

I remember it being a pretty quiet ride home. My dad’s colleague asked me if I was looking forward to my birthday, and I excitedly said I was (it was coming up in just over a week). I don’t remember much else about the ride.

When we got home, we all walked into the house. My grandpa (who lived with us at the time) passed by and said hello.  We sat down in the living room and my dad gave us the news. By then he was crying and I knew something was wrong.

“I don’t know how to tell you this, but Mom and Brandon were in a car accident and died.”

We all just sat there for a minute, hugging each other and crying. I walked into my bedroom, passing by my now-deceased brother’s bed. 

I paced around the basement, and went outside and paced around the mailbox, not knowing what the heck to do. 

The next week or so was a frenzy of family suddenly coming together. That evening my grandpa picked us up and there were a bunch of people at their house. It was a shock to everyone. Almost immediately family started showing up from everywhere, coming from as far as West Virginia. It’s so odd feeling this way, but much like how you feel a sense of solidarity after a big disaster, that’s the sort of feeling we all felt when everyone showed up all of the sudden. 

The funeral home we were working with was sadly familiar; I had a baby brother the year prior and he died after eleven days. It’s not the kind of place you want to be familiar.

We had the funeral at the church my grandparents attended, and everybody came to it, even my teachers. It was the same church my parents were married in. I’m not religious anymore, but that particular church on the hill does holds a lot of memories.

When you say goodbye to someone, you often don’t ever really know that it’s going to be the last time. And you can’t assume that it will be, either, because then after awhile you’ll just get desensitized to the possibility after awhile. 

When they died, I didn’t feel like there was a moral to the story; it was just a terrible thing that happened. There was no underlying lesson about appreciating those around you while you still can. You don’t start thinking in terms of that until you get older and you start trying to see meaning in events. And as I got older, I did start to think of that accident as a lesson in appreciating your loved ones and understanding that life is fragile.

But the truth is, the accident had no meaning or intrinsic value. I didn’t lose 40% of my immediate family in one day because I needed to learn a lesson in not taking things for granted. And if I really did need that lesson, that was a shit way to teach it to me or my family. 

I’m not a better person for this happening. Changed, maybe, but not better.

Nailing the interview

Since my post on making a great resume was so incredibly well received on Reddit, I don’t want to leave you hanging now that that kick ass resume got you an interview.

Bottom line: the best interview is going to flow a lot like a conversation between new friends. Mixed in with this conversation will be me grilling you with some technical and problem solving questions.

Feel at ease. I want this interview to go well just as badly as you do (because then it means I don’t have to do more interviews!). It’s okay if you feel a little nervous, though. In terms of attire, every person interviewing has their own tastes but as far as I’m concerned you could walk in wearing a T-shirt and jeans and I wouldn’t bat an eye. In fact, I’ll be more skeptical of a suit wearer.

Enthusiasm is a big deal to me. I want to see your eyes light up as you describe your career to me.

You need to be superior at articulating your thoughts. Most engineers are bad at this. If I ask you a hard question and ask you to talk it out, I really fucking mean talk it out because that’s what I’m evaluating. Incoherently rattling random words as you scribble on a whiteboard might yield you a correct answer to the problem, but what do I do when we’ve got a real problem on our hands and I need to talk it out with you?

If you can’t articulate your thoughts in a way that others can understand, you’re probably not a good engineer. It was Einstein who said “if you can’t explain it simply, you don’t understand it well enough.”

If you’re weak at this, practice articulating your thoughts verbally with your colleagues.  Peer review code with your colleagues and talk (or write) out your likes and dislikes. It’s not enough to see a code smell and recognize it. When you can look at the code and say “I see varying levels of abstraction being used in this method. Let’s extract the lower level stuff out for clarity,” that’s good articulation.

When I ask you for your background, don’t recite to me a chronology of your employment history. I love the objectivity, but you’ll sell me better on your ability to articulate your thoughts if you describe your career to me in trends or describe the patterns/progressions your career has taken, and interleave that with concrete instances of things like jobs or projects. Watch how it changes how you sound:

First I worked at A Corp doing C code with Project M, then I worked at B Corp doing more C code with their project MX, then I worked at AB Corp working on C#, then…zzzzzzz….

compared to

I started out with simple bug fixes to the code base at A corp, but as I moved on I really learned I have a knack for improving reliability of software through breaking the code down and into tests, so I took a job at B Corp and helped reel in project MX. I continued to apply those skills in the C# language at AB Corp, and–whoa, is that a job offer already? I just got here!

It makes a difference.

Even more important than your articulation is your ability to actually write code. I am surprised at the number of candidates with years of experience on me who trip up at the simpler programming exercises I give, like fizzbuzz. Even worse: mocking the question as if it’s beneath you (only to answer it wrong).

I often ask a bunch of trivia questions that are things you either know or you don’t. If you don’t, don’t feel bad; it probably won’t be a deal breaker. If you don’t know the answer, try to describe what you do know. For instance:

Q: Does ruby have multiple inheritance? If not, does it offer something similar in its place? # it doesn’t; but it does offer mixins

A1: lol, idk # …

A2: Hmm, I’ve never encountered it working with in Ruby. I know in Python you can do it by listing the superclasses separated by commas. I usually put shared code in modules since you can include many modules in many classes.

Oh, and remember when I said the interview should go kind of like a conversation? I do want to hear questions from you. In particular, I want you to be asking me how our team’s development cycle works. Do we do stuff in sprints? Do we pair? Do we force you to use Vim? Who deploys code? How does an idea get turned into a live feature? What works well about our development process? What doesn’t?  If you don’t care about what your work environment would be at this company, what do you care about?

Ultimately, just be yourself during the interview and that’ll help your interviewer(s) make the best decision. Don’t feel intimidated by being a newbie. Smart companies hire a good mix of junior and senior people. Regardless of skill level, culture fit is a big deal to me. Culture fit doesn’t mean it’s a popularity contest. It’s about your values and what you find important.

Making a good engineer résumé

I routinely review résumés for engineering candidates and I wanted to share some practical tips that are guaranteed to help get you an interview in the instance of at least one person who might be reviewing it.

First and foremost, proofread the living shit out of your resume. You probably rolled your eyes at the English teachers who warned you about it, but they were right. I have thrown out resumes for really well qualified candidates for spelling and grammar errors (even when my colleagues wanted to move forward). I’m not asking that every piece of correspondence you ever have with me is perfect and free of errors. I ask merely that the one-page document that is supposed to tell me whether I should offer you an interview be free of errors.  If you think I’m being pedantic and asking too much of you, that’s fine. Go talk to an interviewer who’s less of a hard ass about that kind of thing, and celebrate your mediocrity together.

My other pet peeve is with language and technology names. It’s JavaScript, not Javascript. It’s MongoDB, not Mongodb. It’s OS X, not OSX. It’s PostgreSQL, not Postgres. Errors like these won’t get your resume thrown away, but I still hold it against you if you didn’t get it right. If you claim to be a master of one of these languages or technologies, spell its name right.

If you work with a recruiter they will probably make your resume look like shit. You’ll know they’re doing this if they ask you to send them your resume in Word doc format. If you’re working directly with the potential employer, send a PDF unless a specific format was requested.  If you are sending a PDF, play with a variety of layouts to see what reads easiest. You could even A/B test different resume layouts with different companies to see if you have better success (though you should really be selective and keep a small pool of prospective employers).

Beyond straightforward things like the above, it’s incredibly difficult to tell the story of what kind of engineer you are in the form of a resume. However, if you are working with a small company with a small engineering team and an engineer is reviewing your resume, don’t name drop every technology you’ve ever encountered in your career. I know that if your resume says you are skilled in Python, Ruby, C, C++, Objective-C, C#, VB.NET, Lua, Brainfuck, Lisp, Clojure, Erlang, Haskell, Node.js, CSS, HTML5, PHP, Java, MySQL, MongoDB, and CouchDB, I know better than to think you’re brilliantly skilled in all of them. even if you’ve done one or more projects in each of these languages throughout your career, but what I really care about is what you’ve mastered, and if you’re smart I’ll know you can learn another language if one comes along.

Don’t stick on extra languages you only had fleeting contact with. Believe me: if a language is important enough that its mere mention gets you an interview, you’ll be found out in the tech interview if it turns out you really don’t know much about that language or technology.  One exception: obscure languages relevant to the posting. If it’s super obscure, even a little experience could get you a real leg up. But your chances are better by just being smart overall.

I don’t know who started the convention of writing your resume in third person in a dry way that avoids using pronouns referring to yourself, but it dehumanizes you as a candidate and it makes the resume a freaking pain in the ass to read. Here’s a confession: I usually don’t have 30 minutes to pore over the resume, so it gets skimmed. The more I can get out of it in that time, the better. Again, this is my own opinion, but I think that as you’re describing your employment history, it works much better to tell a story. Try something like this:

Test Engineer, Acme – 2003-2007

Technologies applied: C, x86 assembly, AnvilTestKit 2.0

I helped optimize Acme’s processes for testing new anvils to bring to market. My team accomplished this by writing automation software on the AnvilTestKit platform and developed the anvil testing industry’s first interface with the Suck-O-Vac system to safely automate cleanup of debris after testing the anvil’s effectiveness. 

See how well that reads? Instead of being some dry list of technologies and buzzwords being strewn all over the place whilst awkwardly trying to avoid using the word “I”, it actually tells a story about the things you actually made (something I personally care a lot about) as well as the technologies you accomplished it with and in what capacity. This gives me a much clearer picture of how familiar you actually are with these languages and technologies. I’m not wondering whether you used C every day of your career there, or if it was just used once when you wrote some random one-off script.  

It’s really popular now to include your GitHub profile in your resume. Some companies actually require it and are using it to determine whether to hire you. I personally don’t place a ton of value in them because I think your best work is probably what you did for your employer (plus I don’t have many projects on GitHub), but if you do include it, I will look at it to see if you actually did something. If all I see are a bunch of forks of others’ projects with few changes, that doesn’t tell me much. Some employers might be using the profile to learn more, though; I don’t know. Perhaps they look at what you starred or issue discussions you’ve contributed to in order to see how you handle yourself. If your GitHub profile isn’t impressive in a way that will push the needle forward for your consideration, keep it out.

Personalize each resume you’re sending out. I sometimes read about some schmo who applied to 300 jobs and didn’t get one call back. If you carelessly fire off your resume to a bunch of employers at once without really researching, they’ll in turn fire off a nondescript rejection letter. Good companies to be an engineer for are really excited about what they do (even if they do something kind of boring) and they’ll let their company culture show in their job posting or on their web site. 

Finally, use the cover letter to your advantage. If you’re doing enough research about a company you’ll have a good understanding of the things they value and maybe even have some insight into how they work (maybe they use a particular Agile methodology, perhaps they pair, maybe they’re remote, etc.). The cover letter’s a great time to casually mention your enthusiasm for things they do. It’s also a good opportunity to be a little more human. If you’re scared to talk in first person on your resume, you can get a bit more warm and friendly in the cover letter. Stay objective, though. Don’t use bullshit descriptors like “team player,” “self starter,” “motivated,” “dynamic,” etc. Instead, talk about things like what your philosophies are on writing good code. Do you value peer review? Mention it. Do you subscribe to the church of test driven development? Mention it! It’s absolutely possible that some of these things are deal breakers for your would-be employer, and maybe they do things that would be deal breakers for you. As engineers we’re blessed right now with a very strong job market giving us the luxury of being able to be a little pickier about the jobs we take, and I consider it a luxury from an employer’s perspective too, because I don’t want workers clinging onto a job that isn’t right for them because it’s so damn hard to find another job.

Ultimately, it’s your resume’s job to get you the interview. If you’re a competent engineer your resume should reflect that (you can’t resume yourself out of incompetence or lack of experience). The tone should come off as friendly and eager to chat, but not so comfortable you seem cocky. It’s the interview’s job to determine the less tangible things, like whether you’re a good culture fit (something I can tell within about a minute of starting to talk to you), details about what you did in previous jobs, or how good you are at technical questions. But until that interview happens, you’re only as good as the resume in my inbox.