Try this first

Read this instruction: “Make the error messages friendly and helpful.”

Now write down what you think three of those messages would say. Then read on.

Why describing words fail

“Friendly” is a word about a feeling. To turn it into text, the model must guess your taste.
It has read millions of error messages, ranging from “ERR_CONN_REFUSED” to “Oops! Something
went wrong 🙈”. Any of those could be “friendly” to somebody.

Now compare. Here is the same instruction, shown instead of told:

Error messages should look like these:

  "We could not find that card. It may have been deleted."
  "Your session has ended. Please sign in again to continue."
  "Could not save right now. Please check your connection and try again."

Not like these:

  "Error 404"
  "Oops! Something went wrong 🙈"
  "InvalidCardException: card_id not found in table cards"

Nobody can misunderstand that. It fixes the tone, the length, the level of detail, the fact
that no emoji are wanted, and the fact that internal error names must not be shown to users.
Six decisions, communicated without one describing word.

Negative examples are powerful

Notice the “Not like these” section. People forget this half, and it does a lot of work.

Showing what you do not want removes options that a description would leave open. It is
especially useful when the model keeps making the same wrong choice. Instead of explaining
again, show it the thing it keeps doing and mark it as wrong.

Where examples help most

  • Formats. Dates, currency, phone numbers, IDs. Never describe a format. Show it.
  • Tone. Error messages, button labels, emails.
  • Edge cases. The empty list. Zero results. A very long name. A name with unusual
    characters.
  • Structure. If you want data shaped a certain way, paste the shape.

The habit

When you catch yourself writing a describing word, stop and ask: can I show this instead?

Usually you can, and it takes less time than the sentence you were about to write.

Try this before the next lesson

  1. Take three describing words from your request. Replace each with one example.
  2. For one of them, add a “not like this” example.
  3. Ask a model for a list of Indian city names in a format you specify only by example.
    Give three examples and no description. See if it follows the pattern.
PreviousNext