Communication

When preparing feature development work, I write Gherkin-style tickets, which follow the “Given/When/Then” format. Many people call these stories, and I do, too. This technique is incredibly effective! But why? In this post, I’ll try to answer that question. I learned this technique watching the greats at Hashrocket. They’ve been doing it this way since 2008 because it works. I have two complementary arguments for this technique: images and raw text hide complexity, while stories reveal complexity. ...

I’ve been lucky to have worked with some great engineers, and one thing that they tend to do exceptionally well is reporting about their work at meetings. Today I’d like to summarize what I think makes a great standup report. My goal is a report that’s informative, impromptu, and actionable. Informative I try to consistently bring the expected information to my standup report. Time is limited and valuable. On some teams, this is “yesterday, today, blockers.” I often omit yesterday’s work; it’s the past and likely less relevant. Same with blockers, or obstacles in my path; I try to resolve them before the meeting and avoid situations where I’m frequently blocked. ...

Bugs are part of software. Reporting bugs well is a necessary skill in an ever-growing number of job titles. In this post, I’d like to explain how to write a perfect bug report and offer some bug-reporting best practices. What do I mean by ‘perfect’? A perfect bug report allows the receiver to start effectively solving the problem without additional conversation. I’ve found that it’s the standard on great teams. ...

Screenshots of code are common in developer communication, but they come with real drawbacks. Here’s why I try to avoid them. Screenshots happen. People are often under time pressure, on phones, or unfamiliar with best practices. Some people feel more confident communicating with images. I’m here to offer solutions, not shame. Problem Background Why does one post screenshots? To be helpful. You’re stuck and want to provide high-bandwidth information. What could be higher bandwidth than a picture? I appreciate that helpful spirit. ...

When building a demo application, I believe you can often skip authentication. Picture this: a coding school student team demoing a project. Smart and creative folks with lots to offer. Yet they spend half of their limited building and demoing time on auth. Here’s a sample script from the demo: “So we click ’login’ and now we’re on the login page, which we know because the header says ‘Log in.’ Then, we can either log in, sign in, or reset our password. We’re going to log in with a username and password I set up before the demo. I just fill in the username ‘demo-user’, password ‘password’, click ‘submit’, and now… wait for it… I’m on my homepage. See my username in the navbar? That only shows up when I’m logged in.” ...

Me: Hey, I’m experiencing an issue with your software. Here’s a detailed bug report. SAAS Engineer: What you’re describing isn’t possible. Narrator: But it was possible. This is a frustrating, unproductive snippet of a conversation I’ve had a few times in my career. What can we learn? Treat bug reports like gold. For every person who takes the time to fill out your support form, there are many more who just gave up, found a janky workaround, or possibly abandoned your product altogether. It costs them nothing to move on. You might not like the message, or how it was delivered, but you are still lucky that they spoke up. ...

A user opened an issue in Tilex last week that I spent a significant amount of time thinking about and talking about (thanks JB) before responding to. Here’s the truncated request: May I ask you to compile a step-by-step list to set up a running TIL instance? Tilex Issue #286 I knew the answer was ’no’, but I reflected on my answer for a long time. When does documentation become too specific? What’s a fair request of an open source project maintainer’s time? How do I decline a request while still thanking the requester and making sure the interaction remains positive? ...

I’ve been giving technical talks for a few years, and I’m speaking at the Vim Chicago Meetup next month about integrating React with Vim. In this post, I’m going to use that opportunity as an excuse to document my speaking process. Some smart people have written on this subject, and anything I’d have to say is partly inspired by these ideas: Conference Prompts: Or How to Submit Proposals and Influence People How to Prepare a Talk Improve Your Presentations In Under $50 Speaking.io What I learned from reading 429 conference proposals What Your Conference Proposal Is Missing Several of these writers talk about submitting conference proposals, AKA CFPs. I don’t plan to cover that in-depth. Why not? I believe once you can write a compelling proposal, getting accepted is the product of a variety of factors you can’t control. So, submit many proposals, and be like Thomas Jefferson, who once said: “I’m a great believer in luck, and I find the harder I work the more I have of it.” And in the meantime, learn to give a great talk. ...

I created this blog to reflect on my code and development as a programmer. In that spirit, I’d like to make a pitch to anybody reading: you should blog. Why? For me, it’s been an invaluable opportunity to practice explaining my thoughts, and to watch myself grow. Explaining Thoughts Translating technical ideas into words is one of the great challenges of being a programmer. We have to master it. Communicating well with everyone on your team is crucial. ...

Sigils are a mechanism for working with textual representations in Elixir. If you’ve ever made an array of Strings in Ruby with %w(), the API is similar. A neat feature of sigils is that we can make custom variants, or override existing Kernel variants. The latter is generally discouraged. Creating a Sigil Here’s some code I wrote for an exercise, defining a new sigil, u: defmodule SigilWriter do @moduledoc """ Provides a module for creating new sigils. """ @doc """ Defines the new sigil function for `u`. """ def sigil_u(content, _opts) do content |> String.split |> Enum.map(&String.downcase/1) end @doc """ Calls the `u` sigil. """ def split_and_downcase(content) do ~u(#{content}) end end The sigil_u function defines the new u sigil— u is just a convenience method. This function takes the content, splits it, and downcases each word in the list. This only works because u is not already a defined sigil in Elixir. ...