AI Writing, Technical Writing, User Guides

Klariti Primer: 5 Ways to Use Google Gemini to Write Error Messages

Posted on by Alan Thompson
11
Jul

There’s a real skill in writing error messages that provide genuine ‘in the moment’ help to the person looking for answers. You’ve no doubt seen this yourself when you had an issue with a new phone, iPad, or when logging into a website, and tried to figure out what actually is wrong with it. And, just as important, how do you fix it?

Obscure error message codes may help the engineers determine what error you’ve encountered but don’t always tell you, the user, how to fix the product. Now.

I’ve worked in technical writing for over 20 years and spent a lot of time crafting error messages for different platforms. For instance, writing an error message that will appear in a desktop application gives you room to add more context in your instructions. However, when writing an error message for an Apple Watch product you have much less words and space to work with. Conciseness is a key consideration on such a small device.

So, if your role involves either writing or reviewing error messages, this Klariti primer will provide direction on how to write, edit, and maintain your error message library.

Get your copy of the Error Message Templates for MS Word

What exactly is an error message?

In the world of software, an error message is a short, system-generated notification that appears when an unexpected problem occurs. Its purpose is to inform the user that something went wrong or that an unexpected behavior has occurred.

However, a good error message does more than that. For a software developer, it might provide a technical code to pinpoint the issue in the codebase. For a software tester, it’s a flag that a use case has failed. But for the end-user, its main job is to answer three questions:

  1. What happened?
  2. Why did it happen?
  3. What can I do to fix it?

Who are error messages for?

While developers might see them during testing, the primary audience is your end-user. In other words, the customer who bought your product and you want to make sure comes back. And, also, someone that you don’t want to return your product because the error message confused them so much they couldn’t figure out how to fix it.

Remember, they aren’t looking for a technical deep dive; they’re looking help, right now. They’ve hit a wall and they need a quick, clear instruction to get back on course. A good error message respects their time and intelligence, offering a path forward without causing alarm.

Who typically writes them?

It’s often a tag-team effort.

  • Software Engineers might write the initial placeholder message (e.g., Error: Null Pointer Exception on line 342).
  • Technical Writers then translate that technical-speak into clear, user-friendly language that aligns with the product’s voice.
  • UX/UI Designers ensure the message is displayed in a way that is visible but not disruptive.
  • Customer Support & Marketing staff may review the messages to make certain they align with the brand’s tone and don’t create unnecessary support calls.

How can I use Google Gemini to write better error messages?

Think of Gemini as your creative partner in a five-stage process. It’s like having a world-class strategist in your corner during every lap of a race, from preparation to the final sprint.

By the way, these instructions apply to most all AI tools, such as Claude and ChatGPT. I have a preference for Gemini as I live in the Google ecosystem all day.

1. Preparation and Research

Before you write a single word, you need context. Gemini can accelerate this process. Instead of starting with a blank page, you can prompt Gemini with the technical details and ask it to frame the problem from a user’s perspective.

  • How to use Gemini: Feed it the technical error code (e.g., 401 Unauthorized) and your user persona.
  • Example Prompt: “My app has a ‘401 Unauthorized’ error when a user’s session times out. My user is a non-technical project manager. Generate three potential reasons this might happen from their point of view and suggest what they would want to know.”

This front-loads your work with empathy, focusing on the user’s problem, not just the system’s.

2. Writing the First Draft

This is where Gemini excels as a co-writer. Use it to rapidly generate multiple options, helping you break free from your own ingrained phrasing.

  • How to use Gemini: Give it a poorly written error message and ask it to improve it based on a set of principles.
  • Example Prompt: “Rewrite this error message: ‘Authentication Failed.’ Make it clear, helpful, and reassuring. The tone should be professional but friendly. Provide three distinct variations.”

Gemini will return options like, “Your session has expired. Please log in again to continue,” or “Incorrect password. Would you like to reset it?” This gives you high-quality raw material to refine.

3. Editing and Refining for Tone

A consistent tone is vital. Your error messages should sound like they come from the same brand as your marketing copy. I find Gemini really good at adjusting text to fit a specific voice. If you give it your Style Guide, it will reference this when writing the material. You can upload a MS Word or PDF file.

  • How to use Gemini: Provide an error message draft and ask Gemini to tune it.
  • Example Prompt: “Refine this message: ‘You must enter a value in the ‘Last Name’ field.’ Make it sound more encouraging and less demanding, like a helpful coach.”

It might suggest, “Please add a last name to complete your profile,” which feels more collaborative and less accusatory.

4. Collaboration and Bridging Gaps

Error messages are a meeting point for technical and non-technical teams. Gemini can act as a translator. Like in Formula 1, where pit team member has a specialty but must communicate flawlessly, Gemini can help different departments get on the same page.

  • How to use Gemini: Use it to explain technical constraints to a marketing team or user needs to an engineering team.
  • Example Prompt: “Explain to a non-technical marketing manager why we can’t just recover a user’s lost password and must instead send a reset link, focusing on security and user trust.”

5. Updating with a Kaizen Mindset

Products evolve, and so should your error messages. The Japanese principle of Kaizen, or continuous improvement, is perfectly suited here. As features change, your error messages must keep pace.

  • How to use Gemini: Provide the old error message and a description of the product change.
  • Example Prompt: “My old error message for a failed upload was: ‘Error: File too large. Max size 10MB.’ We just increased the limit to 25MB and added support for .MOV files. Please write a new, more helpful error message reflecting these changes.”

Get your copy of the Error Message Templates for MS Word

What are the biggest mistakes to avoid when writing error messages?

  1. Blaming the User: Avoid phrases like “You made an error” or “Invalid input.” It creates a negative experience. Instead, state the problem impersonally: “This password needs one uppercase letter.”
  2. Using Technical Jargon: “Error 0x80070057” means nothing to your user. Always translate cryptic codes into actionable advice.
  3. Providing a Dead End: The worst error message is one that tells the user what’s wrong but not how to fix it. Always provide a next step, whether it’s a link to a help document, a “Try Again” button, or a suggestion.

What are the benefits of well-written error messages?

  • Reduced Support Costs: Clear messages empower users to solve their own problems, deflecting support tickets.
  • Increased User Trust: Helpful, polite messages build confidence and show that you respect the user’s time.
  • Improved Product Perception: Every detail counts. Good microcopy like error messages contributes to the feeling of a polished, professional product.
  • Faster Problem Resolution: For both users and internal teams, a precise message gets everyone to the solution quicker.

Glossary of Terms

  • Error Code: A specific alphanumeric string (e.g., 404, 502) that gives developers a quick reference for a known type of problem.
  • Stack Trace: A detailed report showing the sequence of function calls that led to an error. It’s for developers only and should never be shown to an end-user.
  • User Persona: A fictional character created to represent a key user type. It helps writers and developers maintain focus on the user’s needs and perspective. Get the user story template
  • Tone of Voice: The personality and character of the writing. Is it formal, playful, serious, or encouraging? Consistency is key.

Conclusion

Creating effective error messages takes practice. It requires that you blend technical precision with human empathy. I find that Google Gemini offers an effective way to manage the complexity, accelerate the workflow, and offer creative options you might not have considered. But it remains a tool.

Your expertise—your ability to understand the user’s context and make the final call—is what turns a draft from an AI into a great experience for a real person.

References

Refer to the following sites for more guidelines and examples

  1. Nielsen Norman Group: Error Message Guidelines
  2. Google Material Design: Help & feedback (See sections on providing feedback)
  3. Atlassian Design System: Messages

Get Templates – Instant Download:

Connect with us

Alan Thompson