مستندی که ساعت سه صبح به دادت می‌رسد

منبع مفهومی: On-Call — Google SRE Workbook. قالب و نمونه این یادداشت، طراحی پیشنهادی مستقل برای مستندسازی عملیاتی است.

مستند مفید باید در لحظه‌ای که تمرکز کم و فشار زیاد است، تصمیم بعدی را روشن کند. از نظر من، برای شروع یک صفحه دقیق بهتر از پوشه‌ای بزرگ با دستورهای قدیمی است. البته یک صفحه فقط نقطه ورود است؛ جزئیات تخصصی می‌توانند در مستندهای پیوندخورده بمانند.

چه چیزهایی باید در صفحه اول باشند؟

• کاربرد و اهمیت: این سرویس چه کاری برای کاربر انجام می‌دهد و توقف آن چه اثری دارد؟
• مالک و مسیر ارجاع: مسئول فنی، جانشین و روش تماس سازمانی کجاست؟
• وابستگی‌ها: نام منطقی سرویس‌های لازم، محل تنظیمات و ترتیب بررسی چیست؟
• سلامت و شواهد: آزمون موفق کاربر، محل لاگ و نشانه‌های خطای شناخته‌شده کدام‌اند؟
• بازیابی و برگشت: لینک رویه تأییدشده، محل مرجع بکاپ و شرایط توقف عملیات چیست؟
• اعتبار مستند: چه کسی و در چه تاریخی آن را با وضعیت واقعی تطبیق داده است؟

یک نمونه فرضی

برای «سامانه گزارش داخلی» می‌توان نوشت: وظیفه، نمایش گزارش روزانه است؛ وابستگی ضروری، پایگاه داده گزارش است؛ آزمون سلامت، ورود حساب آزمایشی و بازشدن گزارش نمونه است؛ در صورت خطا، ابتدا زمان رخداد و شناسه درخواست ثبت و سپس لاگ برنامه بررسی شود. نام‌ها و مسیرهای واقعی باید توسط مسئول همان محیط تکمیل شوند.

ارزش این نمونه در تعداد فیلدها نیست؛ نفر بعدی می‌فهمد از کجا شروع کند و کدام نتیجه را معتبر بداند. دستورهایی مثل «اگر خراب شد ری‌استارت کن» بدون شرط، اثر جانبی و معیار موفقیت، راهنمای قابل‌اتکایی نیستند.

مستند هم نیاز به آزمون دارد

از همکاری که نویسنده صفحه نیست بخواهید یک سناریوی آزمایشی را فقط با همان راهنما دنبال کند. هرجا مجبور شد شفاهی سؤال کند، احتمالاً یک ابهام واقعی پیدا شده است. بعد از تغییر مهم سرویس هم مستند را بازبینی کنید.

پیشنهاد من: رمز، توکن و کلید خصوصی را داخل صفحه نگذارید؛ فقط روش دسترسی مجاز به مخزن امن را ذکر کنید. مستند باید پیدا‌کردنی و متناسب با سطح دسترسی مخاطب باشد. نسخه عمومی یا نمونه آموزشی را هم از اطلاعات واقعی شبکه جدا نگه دارید.

مطالعه مرتبط: چک‌لیست پیش از ری‌استارت.