Stuff Everybody Knows A guide to the rest of your web development career

Chapter 3 of 15

Communication Is Half Your Job

Producing code is no good if you can't communicate about it.

So you’ve learned that you don’t know anything and that you should do as little as possible. A solid grounding for a professional career as a web developer, you can start slinging code, right?

Half-right. Half of your job is getting code out into the world. The other half is communicating about the code. You need to know what the problem is, which is much more tricky and nuanced than you might think. You also need to tell other people about your solution, an equally complex challenge.

Understanding the problem

Every engineer’s job starts with communication. Sure, you can write the perfect algorithm (or your agent can) but how do you know the problem you needed to solve? You need to understand what people are asking for, the problems they are actually having, and particularly the constraints that you are working within.

If somebody tells you “build me an email client”, that sounds easy. Email is a solved problem, you know what the client should look like, you’ve already got a list of features in your head. It’s tempting to dive straight in.

Instead, the very first question out of your mouth should be “How long do I have?” Even at agentic speeds, building the perfect solution is going to take much longer than building something that’s ready in an hour. Do they need it an hour from now? They might. Taking way too long for a perfect solution when somebody needed a good-enough solution yesterday is a classic mistake by junior developers.

Here are some other key questions, which are all about constraints:

  • How much can it cost?
  • How many users will it have?
  • How much data will it need to handle?
  • How many machines will it run on?
  • Does it need to be fast, or does it need to be cheap, or does it need to be perfect? (Pick two)
  • Will external, unfriendly users be able to access this?
  • If it breaks, how much of a problem is that?

But above all, “How soon do you need it?” is going to override everything else, and they will be glad you asked.

Communicating your solution

Once you’ve built the thing, your next job is to communicate what has been built. This often involves communicating to stakeholders who weren’t around at the time what the constraints were that you built it under. If you built it cheaply and quickly, they need to know that. If it’s not ready for external users, they need to know that too. If it has every feature you can possibly imagine, you’re going to need to communicate what those are, because your users are not going to find them all on their own.

There are several ways you can communicate:

Documentation

All of this should be captured in documentation.

If you don’t write documentation, you’re going to find yourself in meetings, over and over, explaining the same thing. Or worse, some other people are going to have a meeting without you, totally misunderstand what it is that you built, decide that it isn’t useful for their needs, and throw it away. A system that nobody uses is just as bad as a system you never built in the first place. So write documentation, so people will understand your thing, what problem it solves, and how to use it.

Meetings

Sometimes, despite your best efforts, you’re going to find yourself in a meeting. I’m sorry. It’s probably not your fault. But you can come prepared to have an effective meeting.

The best meetings are:

  • Short. Humans lose focus after 20 minutes and start repeating themselves. Try to keep everything under half an hour.
  • Focused. A meeting should really only be about one thing. At most, a handful of things. A meeting with a 10-point agenda is a meeting where you will talk about the first 3 things and then everyone will be too tired to substantively discuss everything else.
  • Decision-oriented. A meeting should be the place where a bunch of people who have already done the reading come to make a decision, and maybe clarify a few points beforehand. If you have spend the meeting reading through a presentation, you should have sent them the presentation in advance. You’re just wasting everyone’s time, especially your own.

Talks

A talk is like a meeting where nobody gets to talk except you. Talks are tricky, because a lot of talks can be substituted with documentation. If that’s true of your talk, don’t give your talk, just give people a link to the documentation and let them read it in their own time.

But sometimes a talk is useful. Talks are people giving you 20 focused minutes of their time in which you can teach them something by guiding them through a narrative. That’s different from documentation, which tends to be comprehensive and multi-branched. A talk takes a point of view, a single thread, and runs them through it.

The 20 minutes part is unfortunately non-negotiable. Even if you’ve got an hour of their time, you’re only have their attention for the first 20 minutes. So cram the good stuff in there.

Code itself

This one is here as a trick. There are some people who believe code should be self-documenting, that the code is the one thing that teaches how they system really works. Those people are wrong. Nobody but nobody is ever going to read your code and understand the constraints you were under when you wrote it, because that information is not captured in the code, and the constraints are the important part. Do not expect people to read your code, and don’t read other people’s code. Go find them and force them to write some fucking documentation, that’s a much better use of your time.

Now you’re ready to get to the actual coding part of your job. You thought it would never happen, right?