One of the best pieces of advice I’ve received in my career is a three-word phrase: Read the words.

It is deceiving in its simplicity, but keeping this mantra in mind has helped me many times across all sorts of situations.

The idea is exactly what it says: if there are some words associated with the thing you’re doing, did you read them? I mean really read them? Every word? If not, go back and do that.

Are you debugging some code? What does the error message say? All of it, not just the first or last three lines. Did you join a Slack thread halfway through? Scroll back and read the whole thing. Don’t just skim the last few messages. This also applies to emails, docs, pull requests, meeting notes, user stories: basically anything with text. If there are words, read them. You get the idea.

I am not writing this from a position of superiority as someone who always reads the words. But, I always wish that I did.

Debug

The first example where this is really useful is in software engineering and debugging. Let’s say you’re working on something and it throws an error. Did you read the error message? I don’t mean scan it. Humans are natural pattern matchers. We are very good at extrapolating a full picture from limited information. While useful in the “that big shadow in the dark must be a bear and is definitely not just a rock” scenario, in a “I am reading a Python traceback” context, making assumptions and jumping to conclusions usually results in rabbit holes and wasted effort.

To demonstrate, here’s an example where I failed to do this recently. I was working on some code that consumes an API. The API supports a bookmarking strategy: it takes a since query parameter so you can grab events you haven’t already consumed. You store the “last ingested event” bookmark, and next time you run the ingestion, you pick up from that point.

url = "https://my-api.com"
jwt_token = get_token()
bookmark = get_bookmark()

if bookmark:
  url = f"{url}?since={bookmark}"

LOGGER.info(f"Attempting request: {url}")
response = requests.get(url, headers={"Authorization": jwt_token})

if response.status_code != requests.codes.ok:
    LOGGER.info(f"Error processing {url} - Status code: {response.status_code}")
    response.raise_for_status()

I had this working fine when testing running without a bookmark (i.e. ingest everything from scratch). Once I’d confirmed connectivity, I wanted to test bookmark functionality. I uploaded a bookmark file for the app to consume, ran it, and:

1: INFO:__main__:Attempting request: https://my-api.com?since=12345
2: 
3: INFO:__main__:Error processing https://my-api.com?since=12345
4: - Status code: 403
5: Traceback (most recent call last):
...
6: requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: https://my-api.com?since=12345
7:

403? Oh no! I must have hit some rate limit! The API owners must have revoked my token! That’s what 403 means right?

I contacted the owning team asking if they had revoked my token. While waiting for a response, I tried deleting the bookmark, maybe my code was wrong? Maybe the param was page_since? Maybe I needed to set a limit?

Savvy readers will notice what took me over an hour to realise. The logging code looks like this:

LOGGER.info(f"Error processing {url} - Status code: {response.status_code}")

When we run it:

1: INFO:__main__:Error processing https://my-api.com?since=12345
2: - Status code: 403

See the newline? The file I had uploaded looked like this:

1: 12345
2:

Instead of:

1: 12345

The newline broke the query param. Imagine how much time and pain I would have saved by just reading the words. It’s a subtle thing, but actually reading the error message line by line would have shown me the real error. When I realised what I had done, the first thing I thought was “Oh Matt, read the words mate”.

I made this mistake during development, when I had all the time in the world. But in a production failure scenario, fixing code doesn’t come with ideal conditions. When the pager goes off at 11:30 PM, dashboards are red, and people are pinging you for updates, your brain starts cutting corners. You half-read logs, assume the cause, pattern-match to a similar issue you resolved six months ago, and dive into fixing the wrong thing. That’s why read the words is such a useful mantra. It’s a reminder to slow down just enough to actually read the error message, not just glance at the exception type. To look at the stack trace, not just the top line. To double-check the input, not just assume it’s what you expect.

Chat Apps

The read the words mantra is not just applicable to technical examples. It’s just as useful in communication (probably even more so).

In our modern remote work world, a lot of communication happens through chat apps like Slack (or if you are unlucky, MS Teams). Other than being a massive distraction from focussed work, chat apps also overload our monkey brains with an absolute torrent of text. Because of this, we have a tendency to not actually read the content, but to scan through it, and make assumptions. How many times has this happened to you?

You: I’ve deployed the fix, just waiting on the pipeline to catch up, should be good to go in an hour

Fred (three messages later): When is the fix getting deployed?

You: …

This happens all the time.

In its worst variations, this phenomenon results in slowed-down communication, repeated information, derailed conversations and cranky people. The fact is, you’ve probably been our friend Fred more than a few times. I know I have more often than I’m proud to admit.

Luckily, there is an easy solution. To avoid being Fred, you guessed it: read the words. Before you jump in, scroll up. Read the whole thread. Get the context. If you don’t understand a message, re-read it.

This isn’t just useful for threads. This is also useful for:

  • Announcements: Read the whole message before asking what date the event is on
  • DMs: Are you asking something that someone already answered in their original message?
  • Status Updates: Did you read the attached meeting notes and docs before asking what is going on?

If our aim is to be effective, we want to be responsive, not reactive. When you read the words, you’ll have all the information you need to succeed, and people will love you for not making them repeat themselves or passive aggressively post links to already answered questions.

Applications — How To Read The Words

This is applicable beyond debugging and Slack threads. Any time there is text related to something you are doing, you should read it. Here’s some tips I’ve found useful myself when using this mantra:

Slow down

Take a breath. Think about it. If something is urgent, wouldn’t you rather have as much information as possible before making a decision, or committing to a plan of action? Of course, we will never have the complete picture, or all the facts, but let’s not ignore the ones we do have by not reading them.

What do you know? (Not what you assume you know)

Don’t start with what you assume to be the truth. Start with what you can see. What has actually happened? What does the message say? Once you have all the available information, use your amazing powers of gap-filling on the actual gaps.

Can you repeat it back to someone?

If someone has sent you a message, and you’ve read it, and you’re pretty sure you understand what they’ve said, a really great way to make sure is to reword it and repeat it back to them.

  • Okay, so just to be clear, you’re saying that…
  • I just want to double check, this is what has happened so far…

Doing this not only validates your own understanding of the words, but it also validates the person who took the time to write them (“they actually care about what is going on”). This repeating process is also an important part of applying the Principle of Charity. This avoids misinterpretation, and makes sure we are all on the same page when discussing something.

Trust, but verify

Sometimes, someone will tell you what “the words” said. It is better to read the words yourself and make sure what you’ve been told matches reality. There are children’s games that demonstrate the phenomenon of distorted information when passed through a filter, and the same is true when you receive information through a second-hand source. Where possible, verify the words by reading them yourself. Note that when I say “someone” here, I am also talking about LLM and “AI” summary features that are increasingly built into every application. (the mantra after all is not read a summary of the words).

Thanks for reading these words

Read the words has saved me a lot of pain. I’m not perfect, but every time I forget to do this, I wish I’d taken my own advice.

Next time you’re staring at some log messages or a confusing Slack thread… remember to really read what you are looking at.

Thanks again for reading these words. If this mantra has helped you, I’d love to hear about it.