Technical Writing and Documentation 101: Error Messages and In‑Product Copy (Microcopy)

Error Messages and In‑Product Copy (Microcopy)

Error Messages & In-Product Copy (Microcopy) – Study Guide

A practical, portfolio-ready guide for technical writers, developers transitioning into writing, and writers modernizing their skills.

What This Is

Error messages and in-product copy (microcopy) are the small but critical snippets of text that guide users when things go wrong or when they need quick instructions inside a product. Well-written microcopy reduces support tickets, improves user confidence, and prevents frustration. For example, a payment API’s error message like "Invalid card number (must be 16 digits)" is far more helpful than "Error: 400 Bad Request". Similarly, a cloud service’s onboarding tooltip—"Click ‘Deploy’ to launch your first instance (takes ~2 min)"—sets clear expectations and reduces abandonment.

Key Terms & Tools

• Microcopy: Short, action-oriented text in UIs (buttons, tooltips, placeholders, error messages) that guides users. Example: "Drag files here to upload" vs. "Drop files."
• Error messages: Notifications that explain what went wrong, why, and how to fix it. Example: "Your session expired. Refresh the page to log in again."
• Docs-as-Code: Treating documentation like code—stored in Git, written in Markdown/AsciiDoc, reviewed via PRs, and built with static site generators (e.g., Sphinx, Docusaurus, MkDocs).
• OpenAPI (Swagger): A specification for describing REST APIs. Tools like Swagger UI or Redoc auto-generate interactive docs from OpenAPI files.
• i18n (Internationalization): Designing text to be easily translated. Example: Avoid "Click the blue button" (color may not translate culturally) and use "Click ‘Submit’" instead.
• A/B testing: Comparing two versions of microcopy to see which performs better (e.g., "Try for free" vs. "Start your free trial").
• Voice & tone guides: Rules for how your product "speaks" (e.g., Google’s Material Design guidelines, Mailchimp’s Content Style Guide).
• Figma/Storybook: Design tools where writers collaborate with UX designers to place microcopy in prototypes.
• Linters (e.g., Vale, TextLint): Tools that enforce style rules (e.g., "Don’t use ‘please’ in error messages").
• Analytics (e.g., Hotjar, FullStory): Track how users interact with microcopy to identify pain points (e.g., high clicks on a confusing error message).
• Accessibility (a11y): Writing for screen readers (e.g., "Error: Invalid email" vs. "Error: The email you entered is invalid. Example: [email protected]").
• Localization (l10n): Adapting microcopy for different languages/cultures. Example: "Log in" (US) vs. "Sign in" (UK).

Step-by-Step / Process Flow

How to Write Effective Error Messages & Microcopy

1. Understand the context
2. Read the product spec, talk to engineers/designers, and test the feature yourself.

3. Example: For an API error, check the HTTP status code (e.g., 401 Unauthorized) and the backend logic (e.g., "Missing API key").

4. Draft clear, actionable text

5. Error messages: Explain what happened, why, and how to fix it.
   • ❌ "Payment failed."
   • ✅ "Payment declined. Your card was rejected by the bank. Try another card or contact your bank."

6. Microcopy: Be concise but helpful.

   
   
   • ❌ "Enter your email."
   • ✅ "Enter your email to reset your password (e.g., [email protected])."

7. Collaborate with UX/engineering

8. Use Figma or Storybook to place microcopy in the UI.

9. For APIs, update the OpenAPI spec (e.g., description: "The API key is missing or invalid. Include it in theAuthorizationheader.").

10. Test with real users

11. Run A/B tests (e.g., "Oops!" vs. "Error" in a 404 page).

12. Use Hotjar to see if users struggle with a tooltip or error message.

13. Document internally

14. Add microcopy to a shared style guide (e.g., Notion, Confluence) with examples.

15. For APIs, include error responses in the OpenAPI spec under responses:
    yaml
responses:
401:
description: "Unauthorized. The API key is missing or invalid."

16. Automate and enforce consistency

17. Use a linter (e.g., Vale) to flag style violations (e.g., passive voice, jargon).
18. For APIs, auto-generate docs from OpenAPI using Swagger UI or Redoc.

Common Mistakes

Tech Writing Interview / Portfolio Tips

1. Show, don’t tell
2. In your portfolio, include before/after examples of microcopy or error messages you improved.

3. Example: A GitHub PR where you updated an OpenAPI spec to add clearer error descriptions.

4. Highlight collaboration

5. Mention tools like Figma, Storybook, or Swagger UI to show you work with designers and engineers.

6. Example: "Collaborated with UX to rewrite onboarding tooltips, reducing support tickets by 20%."

7. Know the difference between tools

8. Swagger UI vs. Redoc: Swagger UI is interactive (lets users test endpoints); Redoc is static but prettier.

9. Tutorial vs. How-to guide: A tutorial teaches concepts by building (e.g., "Build a weather app with our API"); a how-to solves a specific problem (e.g., "How to authenticate with OAuth").

10. Prepare for scenario questions

11. Example: "A developer says your API error messages are unhelpful. How do you fix this?"
12. Answer: "I’d audit the OpenAPI spec, add detaileddescriptionfields for each error, and test endpoints in Postman to ensure messages match real responses."

Quick Check Questions

1. A user complains that an error message is confusing. What’s your first step?
2. Answer: Reproduce the error to understand the context, then rewrite the message to explain what happened, why, and how to fix it.

3. Why: You can’t improve what you don’t understand.

4. Your team wants to localize microcopy for Spanish markets. What do you need to consider?

5. Answer: Avoid culture-specific metaphors (e.g., "Hit a home run"), use i18n-friendly strings (e.g., "Log in" → "Iniciar sesión"), and test with native speakers.

6. Why: Direct translations often fail to convey the intended meaning.

7. An engineer says, "Just use the HTTP status code in the error message." How do you respond?

8. Answer: Explain that HTTP codes (e.g., 404) are for machines, not users. Add a human-readable message like "The page you’re looking for doesn’t exist. Check the URL and try again."
9. Why: Users don’t know what 404 means.

Last-Minute Cram Sheet

1. Error message formula: Problem + Cause + Solution. Example: "Payment failed (your card was declined). Try another card or contact your bank."
2. Microcopy length: Aim for < 12 words (e.g., "Uploading… 3/10 files").
3. ⚠️ Avoid "please" in errors (e.g., "Please try again" → "Try again").
4. OpenAPI error example:
   yaml
responses:
400:
description: "Invalid input. The `email` field must be a valid email address."
5. Markdown for microcopy: Use bold for buttons (e.g., Click Submit.) and `code` for placeholders (e.g., Enter yourAPI_KEY``).
6. A/B test microcopy with tools like Google Optimize or Optimizely.
7. Accessibility tip: Use aria-label for screen readers (e.g., <button aria-label="Close modal">X</button>).
8. ⚠️ "Tutorial" ≠ "How-to guide" (tutorial = build to learn; how-to = solve a problem).
9. Swagger UI vs. Redoc: Swagger is interactive; Redoc is static and prettier.
10. Linter rule example: "Avoid passive voice in error messages (e.g., ‘An error occurred’ → ‘We couldn’t process your request’)."