قالب گزارش باگ خوب: چه چیزی باید داخلش باشد
در این مقاله میخوانید
گزارش باگی که نتوان بازتولیدش کرد، حل نمیشود. و بیشتر گزارشها قابل بازتولید نیستند — نه به این دلیل که گزارشدهنده بیدقت است، بلکه چون کسی به او نگفته چه چیزی لازم است.
این مقاله یک قالب آماده است، بهعلاوهٔ توضیح اینکه هر بخش چرا آنجاست.
قالب
عنوان:
[یک جمله: چه چیزی، کجا]
چه کردم:
۱.
۲.
۳.
چه انتظاری داشتم:
چه دیدم:
هر بار تکرار میشود؟ بله / نه / گاهی
محیط:
مرورگر و نسخه:
دستگاه:
آدرس صفحه:
اسکرینشات: [پیوست]چرا هر بخش لازم است
عنوان
باید در فهرست، بدون باز کردن، قابل فهم باشد. «مشکل در سایت» بیفایده است؛ «دکمهٔ ثبت سفارش در موبایل کار نمیکند» در یک نگاه اولویت را مشخص میکند.
مراحل — مهمترین بخش
«روی ذخیره زدم و ارور داد» قابل بازتولید نیست. آنچه لازم است:
۱. با حساب کاربری عادی وارد شدم
۲. به صفحهٔ ویرایش پروفایل رفتم
۳. فیلد ایمیل را خالی کردم
۴. روی «ذخیره» زدممعیار خوب بودن: آیا کسی که سیستم را نمیشناسد میتواند فقط با خواندن اینها، همان نتیجه را بگیرد؟
انتظار در برابر واقعیت
این دو خط گاهی معلوم میکنند که اصلاً باگی در کار نبوده و انتظار اشتباه بوده — که خودش یافتهٔ ارزشمندی است، چون یعنی رابط کاربری گیجکننده است.
تکرارپذیری
یک کلمه که مسیر تحقیق را کاملاً عوض میکند. «هر بار» یعنی باگ منطقی است. «گاهی» یعنی احتمالاً مسئلهٔ زمانبندی یا وابسته به داده است — و توسعهدهنده از همان ابتدا جای دیگری را میگردد. انواع باگ را در باگ نرمافزاری چیست؟ دستهبندی کردهایم.
محیط
بخش بزرگی از باگها مخصوص یک مرورگر یا یک اندازهٔ صفحهاند. بدون این اطلاعات، توسعهدهنده روی کروم دسکتاپ تست میکند، مشکلی نمیبیند، و گزارش را میبندد. این یکی از دلایلی است که باگها فقط در production ظاهر میشوند.
اسکرینشات
تفاوت بین توصیف و شواهد. یک تصویر معمولاً چیزی نشان میدهد که گزارشدهنده اصلاً به آن اشاره نکرده بود.
و حالا مشکل این قالب
اگر این قالب را جلوی کاربر عادی بگذارید، اکثریت قاطعشان پرش نمیکنند. هشت فیلد برای کسی که فقط میخواست خریدش را تمام کند، خیلی زیاد است. نتیجه: فقط عصبانیترین کاربران گزارش میدهند و بازخوردی که میگیرید نمایندهٔ بقیه نیست. چرا کاربران باگ گزارش نمیدهند دقیقاً همین را بررسی میکند.
راهحل این نیست که قالب را کوتاه کنید و اطلاعات کمتری بگیرید. راهحل این است که بیشتر فیلدها را خودتان پر کنید. این همان اصلی است که در چطور از کاربران بازخورد واقعی بگیریم گفتیم: زمینه را خودتان جمع کنید، نه از کاربر.
چه چیزی را نباید بپرسید
نرمافزار شما اینها را از قبل میداند و پرسیدنشان فقط اصطکاک است:
- مرورگر و نسخهاش
- دستگاه و اندازهٔ صفحه
- آدرس صفحه
- خطاهای کنسول در همان لحظه
- مسیری که کاربر تا اینجا طی کرده
- اسکرینشات — میشود خودکار گرفت
- هویت کاربر، اگر وارد حساب شده
چه چیزی فقط از کاربر برمیآید
- چه کاری میخواست بکند
- چه انتظاری داشت
یعنی قالب واقعی برای کاربر نهایی، همین دو مورد است — و در عمل معمولاً یک کادر متن کافی است. بقیه را سیستم ضمیمه میکند.
یک نمونه، بد و خوب
تفاوت را در عمل ببینید. همان باگ، دو گزارش:
گزارش بد:
عنوان: سایت خرابه
متن: نمیشه سفارش داد لطفا درست کنیدتوسعهدهنده چه میداند؟ تقریباً هیچ. باید بپرسد کدام صفحه، کدام مرورگر، چه کردید، چه دیدید — و هر سؤال یک روز رفتوبرگشت است.
گزارش خوب:
عنوان: دکمهٔ «ثبت سفارش» در موبایل هیچ واکنشی ندارد
چه کردم:
۱. با گوشی وارد سایت شدم (سافاری، آیفون)
۲. یک محصول به سبد اضافه کردم
۳. به صفحهٔ تسویه رفتم و فرم را پر کردم
۴. روی «ثبت سفارش» زدم
انتظار داشتم: به درگاه پرداخت برود
دیدم: هیچ اتفاقی نمیافتد، دکمه فقط کمی تیره میشود
هر بار تکرار میشود؟ بله، سه بار امتحان کردم
روی لپتاپ همان حساب کار میکند
مرورگر: Safari، iOS 17
آدرس: example.com/checkout
[اسکرینشات پیوست]این گزارش تقریباً خودش تشخیص را میدهد: مشکل مخصوص سافاری موبایل است، در مرحلهٔ ارسال فرم، و تکرارپذیر. توسعهدهنده میتواند مستقیم سراغ همان مسیر برود.
تفاوت این دو، تفاوت بین چند روز و چند ساعت است — و نکتهٔ مهم اینکه گزارشدهندهٔ دوم لزوماً فنیتر نیست؛ فقط قالبی جلویش بوده که میگفت چه چیزی لازم است.
وقتی گزارش از پشتیبانی میآید
مسیر رایج در بیشتر تیمها: کاربر به پشتیبانی میگوید، پشتیبانی به توسعه. اینجا اطلاعات در هر انتقال کم میشود.
سه کار این نشتی را کم میکند:
- به پشتیبانی چکلیست بدهید — همان قالب، ولی بهعنوان سؤالهایی که موقع صحبت با کاربر بپرسد.
- عین جملات کاربر را نگه دارید. ترجمهٔ «گفت دکمه کار نمیکند» به «باگ در فرم ثبت» ممکن است اطلاعات مهمی را حذف کند.
- مسیر مستقیم هم باز بگذارید. بعضی کاربران ترجیح میدهند خودشان گزارش دهند تا اینکه با پشتیبانی حرف بزنند — و گزارش مستقیم آنها معمولاً دقیقتر است.
دو قالب، نه یکی
اشتباه رایج این است که یک قالب برای همه بگذارید. دو مخاطب متفاوت دارید:
کاربر نهایی: یک کادر متن، اسکرینشات خودکار، و تمام. هر فیلد اضافه، درصدی از گزارشها را حذف میکند.
تیم داخلی و تستر: قالب کامل بالا. اینها میدانند چرا هر فیلد لازم است و پر کردنش برایشان بخشی از کار است.
چند نکتهٔ عملی
یک باگ در هر گزارش. گزارشی که سه مشکل را با هم میآورد، یا ناقص حل میشود یا معلوم نیست کِی باید بسته شود.
حدس علت را جدا کنید. «فکر کنم مشکل از کش است» ممکن است کمک کند، ولی گاهی توسعهدهنده را به مسیر اشتباه میبرد. اگر مینویسید، صریح بگویید که حدس است.
گزارشهای تکراری بد نیستند. اگر پنج نفر یک چیز را گزارش کردند، این خودش داده است: یعنی مشکل گسترده است. آنها را به هم وصل کنید، نه اینکه با دلخوری ببندید.
جمعبندی
یک گزارش باگ خوب به دو سؤال پاسخ میدهد: چطور دوباره ایجادش کنم، و چقدر مهم است. هرچه بیشتر از پاسخ این دو را خودکار جمع کنید، گزارشهای بیشتری میگیرید و هر کدامشان قابل استفادهتر است.
و معیار نهایی ساده است: اگر توسعهدهنده مجبور شود برای فهمیدن گزارش به گزارشدهنده پیام بدهد، آن قالب کارش را انجام نداده است.
منابع و مطالعهٔ بیشتر
- راهنمای نوشتن گزارش باگ موزیلا — مراحل بازتولید، انتظار و نتیجه
- How to Report Bugs Effectively — سایمن تاتام — چرا «کار نمیکند» کافی نیست
- قالب issue در GitHub — ساختن قالب گزارش برای تیم داخلی
باگماگ را رایگان امتحان کنید
خطاهای سایتتان را خودکار ثبت کنید و بگذارید کاربران با یک کلیک باگ گزارش دهند.
شروع رایگان