Communication

A missing README is rarely just missing documentation. It usually signals other things, too. A project that’s going to be difficult to set up. When I pull down a project without a README, I’m starting from zero. What kind of app is this? What backend, frontend, persistence layer, and dependencies are involved? Has it ever been set up on my operating system? Answering these becomes homework I didn’t ask for. A project whose purpose may not be clearly defined. What is this project? Why does it matter? Shaky domain language. What kind of users do we have (Customers and Employees, or Players and Coaches)? What can those users do? Without a README, this information is needlessly obscure. What if we have great docs outside the repo? Better than nothing, but docs should live close to the code: a text file in the project. This lets documentation travel with the code, ties changes together via version control, and gives the repo a clear front page. ...

One of my favorite engineering questions is: “What’s wrong with this idea?” It drives the conversation away from why the idea might work, and toward why it might fail. That perspective is invaluable when building. I learned this idea from Paul Arden: “If, instead of seeking approval, you ask, ‘What’s wrong with it? How can I make it better?’, you are more likely to get a truthful, critical answer."― Paul Arden, It’s Not How Good You Are, It’s How Good You Want To Be ...

Today I gave a talk to my team about the Twelve-Factor App Methodology. The Twelve-Factor app is an important methodology for building software-as-a-service drafted by developers at Heroku in 2011. It outlines best practices for app setup, portability, deployment, and scalability. I chose to share this because I think it’s relevant to all software engineers, and part of our shared language and conventions. And, I want the teams I work with to follow it, and for each of us to be a champion of its conventions. ...

“I’m still getting this random 404.” Want to sound pro? Banish “random” from your software engineering vocabulary. Considering the Modern Usage “Random” has a modern usage; let’s consider it. Take this example: “I got a random bill from my dentist.” We hear: “This surprising thing, a bill from my dentist, happened.” We get it. It works. So what’s my issue? Merriam-Webster defines “random” as “lacking a definite plan, purpose, or pattern.” And so, this usage is incorrect, because the bill isn’t random: someone at the dentist’s office sent it to you because they believe you owe money. ...

Eight years ago I wrote a post called You Should Blog. In it, I made an argument that I still believe in: public, professional writing is something every engineer should try. Today, I want to share why I write, and have for over a decade. It’s made me better The first reason is that over time, I think it’s made me a better programmer. To give you an example, here’s an opinion I hold, and how writing helped me solidify it: ...

Receiving feature requests is part of running a software team. Here’s how I handle them. What are Feature Requests? Feature requests are requests for behavior in a software product. Sometimes bugs get lumped in, too; it’s often a little messy. Feature requests come from both inside and outside your company. Some are valuable, some aren’t, others contradict things we’ve already built, or may want to build. Some come from customers who are about to churn. Others might make sense for one customer but would confuse others. ...

If something in your software is confusing to a customer, it is confusing. It is! There is something about it, that you might not see, that doesn’t make sense to a nonzero number of your customers. Stop trying to outsmart the bug report and consider it. Will you encounter a few outlier customers who are hard to please? A few more who struggle with what seem like obvious interfaces? Yes and yes. ...

I recently learned a practice for customer communication that I’d like to document. It’s called “Hit It Twice.” The quoted language in here is broad and should be adapted to the situation. Why This Matters Customer issues deserve prompt attention. And, we have to prioritize customer issues that matter. Customers responding to offers of help, or not, tells us how much they care about the issue. “Hit It Twice” Scenario: a customer opens a support ticket. We respond with a proposed solution or a clarifying question, ensuring they have the next step to move forward. ...

I’ve been organizing Meetups for a decade, starting with Vim Chicago and Chicago Elixir, and now running Maine JS from Portland, Maine. Here’s my practical guide on how to start a Meetup group, based on what’s worked for me. How to start a meetup group The steps that follow are in rough order. You’re going to be doing many of them in the beginning; that’s the time when you do the most sustained work. ...

I’ve been a practitioner of Shawn Wang’s ‘Learn in Public’ for years. In this post, I’ll share a list of ways I’ve found to learn in public. I think that learning in public can start with you, then your team, then the world. And so, these are ordered from small and private to big and public. Talk through a tough problem out loud. Instead of holding a difficult problem in your head, try building a solution out loud from a series of facts. “We’re seeing a bug on staging. It affects this page…”. Talk to a duck if nobody is around. ...