DEV Community: Manuel Garcia

Error Messages Are Writing, Too

Manuel Garcia — Fri, 23 Oct 2026 21:07:59 +0000

Error messages are some of the most carefully read sentences in any piece of software. They appear at the exact moment the reader is stuck, often a little frustrated, and looking for help. Yet they are frequently written last, in a hurry, by someone thinking about the code rather than the person on the other side of it.

The good news is that a useful error message follows a simple pattern, and it can be learned like any other kind of editing.

The three parts of a useful message

A clear error message answers three questions:

What happened?
Why did it happen, if that is known?
What can the reader do now?

Most weak messages answer only the first question, and sometimes not even that.

Before:

Error: invalid input.

After:

The date "31.02.2026" could not be read. February has no 31st day. Please enter a date in the format DD.MM.YYYY.

The second version is longer, but every word earns its place. The reader knows which value was wrong, why it was rejected and what a correct value looks like.

Name the thing, not the category

"Invalid input", "operation failed" and "something went wrong" describe a category of problem. The reader needs the specific case.

Whenever the program knows which file, field, value or setting caused the problem, include it in the message. "Could not open config.yaml" is immediately useful. "Could not open file" sends the reader searching.

This also helps when people copy the message into a search engine or a support request. A specific message leads to specific answers.

Speak to the reader, not about the code

Internal terms leak easily into error text: exception names, function names, abbreviations that only the team uses. They make sense to the author and to nobody else.

Before:

NullReferenceException in UserProfileLoader.

After:

Your profile could not be loaded because no account is linked to this email address.

Technical details still have a place. Developers debugging the problem may need the exception and the stack trace. Put those in logs, or below the human-readable message, clearly separated. The first line should be readable by the person who actually sees it.

Do not blame, do not joke

Tone matters more than usual here, because the reader is already having a bad moment.

Avoid blame. "You entered an invalid password" sounds like an accusation. "The password does not match this account" states the same fact neutrally.
Avoid jokes. A playful "Oops!" can feel friendly the first time and irritating the tenth time, especially when work has been lost.
Avoid false certainty. If the cause is only a guess, say "This may be caused by..." rather than presenting it as fact.

Calm, plain language works best. The aim is to sound like a helpful colleague, not a machine and not a comedian.

Offer a way forward

The most important part of an error message is the last one: what the reader can do next. Even when the program cannot fix the problem, it can usually point somewhere.

Retry later, if the problem is temporary.
Correct a specific value, and show the expected format.
Check a specific setting, and name where it is.
Contact support, and say what information to include.

A message without a next step leaves the reader at a dead end. A message with one turns a failure into a short detour.

Review your errors like any other text

Collect the error messages in your project in one list and read them in a row. This simple exercise reveals a lot: inconsistent wording, messages that say the same thing in five different ways, and messages that say nothing at all.

Edit them as you would edit any other text. Check that each one names the problem, explains it where possible and offers a next step. They are short, but for the reader in that moment, they may be the most important words in the whole product.

Your README Has One Job: Answer the First Three Questions

Manuel Garcia — Fri, 23 Oct 2026 21:07:04 +0000

Most READMEs are written by the person who knows the project best, at the moment they know it best. That is exactly why so many of them are hard to use. The author no longer remembers what it felt like to arrive with no context.

A reader landing on a README usually has three questions, in this order:

What is this?
Is it for me?
How do I get it running?

If the first screen answers those three, the README is already better than most. Everything else can come later.

Lead with what it does, not what it is built with

The opening line is the most valuable space in the file, and it is often spent on the wrong thing.

Before:

A lightweight, blazing-fast, TypeScript-first, zero-dependency solution leveraging modern APIs.

After:

Converts Markdown files into a static website. Runs from the command line, needs no configuration for simple sites.

The first version lists qualities. The second describes a result. A reader can decide in five seconds whether the second one solves their problem. With the first, they still have to guess.

Adjectives like "lightweight" or "fast" are not wrong, but they are claims. Put them after the description, and ideally back them up with something the reader can check.

Say who it is not for

This feels counterintuitive, but it saves everyone time. A short line such as "This tool is not designed for sites with more than a few hundred pages" or "Requires Node 20 or later" helps the wrong reader leave early and the right reader stay with confidence.

Limits are information. Leaving them out does not make a project look more capable; it just moves the disappointment to later, usually into the issue tracker.

Make the first steps copyable

The installation section should be something a reader can follow without thinking. That means:

Real commands, in code blocks, in the order they are run.
One path first. If there are four ways to install, show the most common one and link the rest further down the same file.
A visible result. End the section with what the reader should see when it worked, for example the expected output or the address to open in a browser.

That last point is the one most often missing. Without it, the reader finishes the steps and still does not know whether they succeeded.

Keep the order of the reader, not the order of the code

READMEs often grow in the order features were added. The result is a file where configuration options appear before the basic usage, or a contribution guide sits between installation and the first example.

A simple order that works for most projects:

One-sentence description
Who it is for, and key limits
Installation
A minimal working example
Common tasks
Configuration reference
Contributing and licence

Read only the headings of your README. If they do not follow roughly the path a new user takes, reorder them.

Write the example you would want

One small, complete example is worth more than a long list of options. Complete means it can be copied, run and understood without reading anything else. Avoid placeholders that need explanation, such as <your-thing-here>, unless the explanation sits directly next to them.

If the example needs a file, show the file. If it needs a setting, show the setting. The reader should never have to assemble the example from three different sections.

Review it as a stranger

The best test is simple: give the README to someone who has never seen the project and watch where they hesitate. If that is not possible, wait a few days and read it again yourself, top to bottom, following every step literally.

Each place you have to stop and think is a place a new reader will stop and leave. Fix those first. Polish can wait; clarity cannot.