پیام های خطای عملی بنویسید
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این صفحه بهترین روش‌ها را برای نوشتن پیام‌های خطای عملی توضیح می‌دهد که به کاربر می‌گوید چگونه مشکل را برطرف کند تا بتواند هدف خود را تکمیل کند.
هنگامی که کاربر در حال تعامل با برنامه Google Chat است، مواجه شدن با پیام‌های خطا می‌تواند تجربه ناامیدکننده‌ای باشد، زمانی که خطا قابل اجرا نباشد. به‌عنوان مثال، پیام خطا، An error occurred » مفید نیست، زیرا پیام توضیح نمی‌دهد که چه مشکلی رخ داده است، چگونه کاربر می‌تواند مشکل را برطرف کند یا چگونه کاربر می‌تواند کمک دریافت کند. این صفحه نحوه ساختاربندی پیام‌های خطا را توضیح می‌دهد تا با نمایش نمونه‌های عملی و غیرقابل اجرا برای کاربران مفید باشند.
ساختار پیام خطا
یک پیام خطای عملی ساختار زیر را دارد:
- چه اشتباهی رخ داد. گفتن اینکه چرا برنامه چت نمی تواند یک درخواست را تکمیل کند به کاربر کمک می کند مشکل را حل کند. توضیح اینکه چرا یک خطا رخ داده است باعث ایجاد اعتماد می شود.
- چگونه کاربر می تواند به سمت هدف خود پیش برود. گفتن اینکه چه اشتباهی رخ داده است، هرگز کافی نیست. به کاربران بگویید چگونه می توانند از خطا عبور کرده و هدف خود را تکمیل کنند.
- چگونه می توان کمک گرفت. اگر کاربر همچنان گیر کرده است، به او بگویید چگونه می تواند کمک بیشتری دریافت کند. این می تواند یک فرمان
/help یا پیوندی به اسناد برنامه چت شما باشد.
در این مثال، کاربر تاریخی را در قالبی وارد کرد که برنامه چت انتظارش را نداشت. آنها November 19, 2021 نوشتند، اما برنامه Chat انتظار دارد 2021-11-19 .
در اینجا یک نسخه قابل اجرا و غیرقابل عمل از پیام خطا است که برنامه Chat با آن پاسخ می دهد:
خطای عملی
کاربر از برنامه چت می خواهد تا جلسه ای را با شخص دیگری برنامه ریزی کند. برنامه چت با یک پیام خطای خوب و قابل اجرا پاسخ می دهد:
I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.
این پیغام خطا به دلایل زیر قابل اجرا است:
- می گوید چه اشتباهی رخ داده است. برنامه چت قالب تاریخ را نمی شناسد.
- نحوه رفع خطا را با گفتن فرمت تاریخ مورد انتظار به کاربر توضیح می دهد و تاریخ مثالی ارائه می دهد که به افراد کمک می کند بفهمند چه چیزی بنویسند.
- با دستور اسلش
/help کمک بیشتری ارائه می دهد. اگر کاربران هنوز گیر کرده باشند، می دانند چگونه بیشتر بیاموزند.
خطای غیرقابل عمل
کاربر از برنامه چت می خواهد تا جلسه ای را با شخص دیگری برنامه ریزی کند. برنامه چت با یک پیام خطای غیرمفید و غیرقابل عمل پاسخ می دهد:
Enter the correct date format.
این پیغام خطا به دلایل زیر غیر فعال است:
- نمی گوید که آیا این جلسه را برنامه ریزی کرده است. کاربر ممکن است در برنامه ریزی مجدد جلسه مردد باشد، یا ممکن است تصور کند که جلسه برنامه ریزی شده است.
- به کاربر نمی گوید که چگونه تاریخ را قالب بندی کند. به جای اینکه فرض کنیم کاربران می دانند چگونه تاریخ را قالب بندی کنند، باید بگوییم که انتظار فرمت تاریخ
yyyy-mm-dd دارد. - کمک بیشتری ارائه نمی دهد. وقتی کاربران گیر کرده‌اند و نمی‌دانند چگونه ادامه دهند، ممکن است پیام‌رسانی به برنامه چت را متوقف کنند.
آن را امتحان کنید
اکنون که می دانید چگونه خطاهای قابل اجرا را بنویسید، می توانید در سناریوی زیر تشخیص دهید که کدام یک از این خطاها قابل اجرا هستند:
هنگامی که کاربران با schedule کلمات کلیدی به برنامه چت پیام می دهند، یک برنامه چت رویدادهای تقویم را ایجاد می کند. برای ایجاد یک رویداد تقویم، برنامه Chat به احراز هویت کاربر نیاز دارد. اگر کاربری احراز هویت نشده باشد، برنامه چت با یک پیام خطا پاسخ می‌دهد.
کدام پیام خطا قابل اجرا است؟
قبل از اینکه بتوانم جلسه را برنامه ریزی کنم، باید با تایپ /signin وارد شوید. برای کسب اطلاعات بیشتر، /help را تایپ کنید.
این پیغام خطا قابل عمل است زیرا موارد زیر را می گوید:
- چه اشتباهی رخ داد. برنامه چت به احراز هویت نیاز دارد.
- چگونه ادامه دهیم. برای احراز هویت،
/signin را تایپ کنید. - چگونه می توان کمک گرفت. اگر کاربر اطلاعات بیشتری می خواهد، می تواند
/help را تایپ کند.
شما باید احراز هویت کنید.
این پیام خطا غیرقابل عمل است زیرا نحوه احراز هویت را نمی گوید.
وارد شوید.
این پیام خطا غیرقابل عمل است زیرا نحوه ورود به سیستم را بیان نمی کند و به این معنی است که کاربر به جای اینکه به وضوح بگوید از سیستم خارج شده است که گیج کننده است.
نمی توان جلسه را برنامه ریزی کرد.
این پیام خطا غیرقابل عمل است زیرا به کاربر نمی گوید که چرا نمی توان جلسه را برنامه ریزی کرد یا کاربر چگونه می تواند ادامه دهد. هیچ کمکی ارائه نمی شود.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eGoogle Chat app error messages should be actionable, guiding users on how to resolve issues and proceed.\u003c/p\u003e\n"],["\u003cp\u003eActionable error messages clearly explain the problem, provide steps for fixing it, and offer additional help resources.\u003c/p\u003e\n"],["\u003cp\u003eInactionable error messages are vague, lack guidance, and can lead to user frustration and abandonment.\u003c/p\u003e\n"],["\u003cp\u003eUse the actionable error message structure: state the problem, guide the user on fixing it, and offer further help (e.g., \u003ccode\u003e/help\u003c/code\u003e command).\u003c/p\u003e\n"],["\u003cp\u003eWhen writing error messages, assume users need clear instructions and avoid ambiguity.\u003c/p\u003e\n"]]],["Actionable error messages in Google Chat apps should specify what went wrong, how to fix it, and how to get further assistance. For example, an actionable message for an incorrect date format would state that the format is unrecognized, specify the required format (yyyy-mm-dd), and provide a /help command. In contrast, inactionable errors are vague, omit how to correct the issue, and offer no additional support. A sign-in error should also include clear instructions, and help commands.\n"],null,["# Write actionable error messages\n\nThis page describes best practices to write actionable error messages that tell\nthe user how to fix the issue so that they can complete their goal.\n\nWhen a user is interacting with a Google Chat app, encountering\nerror messages can be a frustrating experience when the error isn't actionable.\nFor example, the error message, `An error occurred`, isn't useful because the\nmessage doesn't explain what went wrong, how the user can fix the issue, or how\nthe user can get help. This page describes how to structure error messages so\nthat they're useful to users by showing actionable and inactionable examples.\n\nError message structure\n-----------------------\n\nAn actionable error message has the following structure:\n\n- **What went wrong.** Saying why the Chat app can't complete a request helps the user resolve the issue. Explaining why an error occurred builds trust.\n- **How the user can proceed toward their goal.** It's never enough to just say what went wrong. Tell users how they can move past the error and complete their goal.\n- **How to get help.** If the user is still stuck, tell them how they can get more help. This could be a `/help` command or a link to documentation for your Chat app.\n\nExample error message: incorrect date format\n--------------------------------------------\n\nIn this example, the user entered a date in a format that\nthe Chat app didn't expect. They wrote\n`November 19, 2021`, but the Chat app expects\n`2021-11-19`.\n\nHere's an actionable and an inactionable version of the error message that the\nChat app responds with:\n\n#### Actionable error\n\nA user asks the Chat app to schedule a meeting with\nanother person. The Chat app responds with a good,\nactionable error message:\n\n``I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.``\n\nThis error message is actionable for the following reasons:\n\n- Says what went wrong. The Chat app doesn't recognize the date format.\n- Explains how to fix the error by telling the user the expected date format and gives an example date that helps people understand what to write.\n- Offers more help with a `/help` slash command. If users are still stuck, they know how to learn more.\n\n#### Inactionable error\n\nA user asks the Chat app to schedule a meeting with\nanother person. The Chat app responds with an\nunhelpful, inactionable error message:\n\n`Enter the correct date format.`\n\nThis error message is inactionable for the following reasons:\n\n- Doesn't say whether it scheduled the meeting. The user might be hesitant to reschedule the meeting, or they might assume that the meeting was scheduled.\n- Doesn't tell the user how to format the date. Instead of assuming that users know how to format the date, it should say that it's expecting the date format `yyyy-mm-dd`.\n- Doesn't offer more help. When users are stuck and don't know how to proceed, they might stop messaging the Chat app.\n\nTry it out\n----------\n\nNow that you know how to write actionable errors, can you identify in the\nfollowing scenario which of these errors is actionable:\n\nA Chat app creates calendar events when users message\nthe Chat app with the keyword `schedule`. To\ncreate a calendar event, the Chat app requires user\nauthentication. If a user hasn't been authenticated, then the\nChat app responds with an error message. \nWhich error message is actionable? \nBefore I can schedule the meeting, you must sign in by typing `/signin`. To learn more, type `/help`. \nThis error message is actionable because it says the following:\n\n- What went wrong. The Chat app requires authentication.\n- How to proceed. Type `/signin` to authenticate.\n- How to get help. If the user wants more information, they can type `/help`. \nYou must authenticate. \nThis error message is inactionable because it doesn't say how to authenticate. \nSign in. \nThis error message is inactionable because it doesn't say how to sign in, and it implies that the user is signed out instead of clearly saying so, which is confusing. \nCan't schedule meeting. \nThis error message is inactionable because it doesn't tell the user why the meeting can't be scheduled or how the user can proceed. No help is provided."]]
