مستندسازی فنی بهتر با هوش مصنوعی

خیلی از تیم های فنی مستند ندارند، نه چون اهمیتش را نمی دانند، بلکه چون همیشه کار مهم تری وجود دارد.

Incident تمام شده، سرویس برگشته، Deploy موفق شده و همه می خواهند سراغ کار بعدی بروند.

نتیجه؟

سه ماه بعد همان مشکل دوباره رخ می دهد و کسی یادش نیست دفعه قبل دقیقا چه شد.

هوش مصنوعی می تواند اینجا یک کمک واقعی باشد: تبدیل اطلاعات خامی که همین حالا در اختیار دارید به یک مستند مرتب و قابل استفاده.

اما یک هشدار مهم:

AI نباید جزئیات فنی را از خودش کامل کند.

اگر چیزی در داده شما وجود ندارد، بهتر است بنویسد «نامشخص» تا اینکه با اعتماد به نفس یک IP، Command یا علت خیالی بسازد.

مستند خوب برای چه کسی نوشته می شود؟

قبل از نوشتن، مخاطب را مشخص کنید.

یک Runbook برای مهندس On-call با مستند معماری برای مدیر پروژه یکسان نیست.

از AI بخواهید خروجی را برای مخاطب مشخص تنظیم کند:

این یادداشت ها را برای یک مهندس Linux که با پروژه آشنا نیست به Runbook تبدیل کن.
توضیحات باید اجرایی، کوتاه و مرحله ای باشند.
هیچ Command یا اطلاعاتی که در ورودی من نیست اضافه نکن.

یا:

این Incident را برای مدیر فنی خلاصه کن. روی Impact، Timeline، Root Cause و اقدام اصلاحی تمرکز کن و جزئیات کم ارزش Log را حذف کن.

از چه چیزهایی می توانید مستند بسازید؟

AI می تواند اطلاعات پراکنده را به انواع مختلف مستند تبدیل کند:

• Runbook عملیاتی
• Deployment Guide
• Incident Report
• Postmortem
• Change Log
• Troubleshooting Guide
• Architecture Overview
• Backup/Restore Procedure
• Onboarding Guide
• Handover Document

نکته مهم این است که فرمت باید با هدف مستند هماهنگ باشد.

ساخت Runbook از یادداشت های خام

فرض کنید هنگام حل مشکل این یادداشت ها را نوشته اید:

• nginx روی web-prod
• config در /opt/apps/edge/nginx/sites/app.conf
• قبل از reload باید nginx -t اجرا شود
• certificate در /opt/apps/edge/certs
• reload با systemctl reload nginx
• اگر test fail شد config قبلی از git برگردد

به جای نوشتن دستی، بگویید:

این یادداشت ها را به Runbook تبدیل کن.

ساختار:

1. هدف
2. پیش نیازها
3. مسیر فایل ها
4. مراحل تغییر
5. Validation
6. Rollback
7. نکات خطر

چیزی خارج از اطلاعات من اضافه نکن.

خروجی اولیه در چند ثانیه آماده می شود و شما فقط جزئیات واقعی را اصلاح می کنید.

Runbook باید «قابل اجرا» باشد

یک مستند ضعیف می گوید:

تنظیمات Nginx را بررسی کنید.

یک مستند بهتر می گوید:

1. فایل Config مربوط به دامنه را باز کنید.
2. قبل از Reload با nginx -t Syntax را بررسی کنید.
3. فقط در صورت موفق بودن Test، Reload انجام دهید.
4. بعد از Reload پاسخ HTTPS را بررسی کنید.

مستند عملیاتی باید به حدی دقیق باشد که فرد دیگری بدون تماس با نویسنده بتواند مسیر را بفهمد.

ساخت Incident Report با AI

بعد از Incident معمولا چند نوع داده دارید:

• پیام های Slack یا Telegram
• Logها
• زمان های تقریبی
• Commandهای اجرا شده
• Ticket
• یادداشت شخصی

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

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

بعد از Timeline می توانید Root Cause و اقدامات بعدی را جداگانه تدوین کنید.

تفاوت Symptom، Root Cause و Contributing Factor

AI گاهی این سه را قاطی می کند.

مثلا:

• Symptom: سایت 502 می دهد.
• Root Cause: برنامه روی Port اشتباه Bind شده.
• Contributing Factor: Healthcheck فقط Process را چک می کرده و Port واقعی را تست نمی کرده.

از مدل بخواهید این موارد را جدا کند:

بر اساس داده زیر، Symptom، Root Cause، Contributing Factors و Corrective Actions را جداگانه استخراج کن.
اگر Root Cause اثبات نشده، آن را «فرضیه» علامت بزن.

این دستور جلوی قطعی نشان دادن یک حدس را می گیرد.

مستند تغییرات را از Commit و Ticket بسازید

اگر چند Commit، Issue یا Change Note دارید، AI می تواند آنها را به یک Change Summary تبدیل کند.

مثلا:

این 12 Commit Message و توضیح Ticket را به Change Log تبدیل کن.
تغییرات را در چهار دسته Feature، Fix، Infrastructure و Documentation گروه بندی کن.
اسم فایل های داخلی را فقط اگر برای خواننده مهم است نگه دار.

این روش برای Release Noteهای داخلی بسیار مفید است.

Architecture Document را با سوال شروع کنید

برای مستند معماری، بهتر است مدل اول جاهای خالی را پیدا کند.

بگویید:

می خواهم از اطلاعات زیر یک Architecture Overview بسازم.
قبل از نوشتن، فهرست اطلاعات ضروری که هنوز نداریم را بنویس.

ممکن است سوال هایی مثل این تولید شود:

• Entry Point ترافیک چیست؟
• TLS کجا Terminate می شود؟
• Database کجاست؟
• Backup چگونه است؟
• Secretها کجا نگهداری می شوند؟
• Dependencyهای خارجی کدامند؟

بعد از تکمیل پاسخ ها، مستند بسیار دقیق تر خواهد بود.

مستند را در سطح درست نگه دارید

یکی از مشکلات AI این است که می تواند متن را بیش از حد طولانی کند.

برای جلوگیری از آن مشخص کنید:

این Runbook باید در زمان Incident قابل استفاده باشد.
هر مرحله حداکثر دو جمله باشد.
توضیحات نظری را حذف کن.
هشدارها را در بخش جداگانه قرار بده.

یا برای مستند معماری:

ابتدا یک Executive Summary کوتاه بده، سپس جزئیات فنی را در بخش های جدا قرار بده.

Validation را بخشی از مستند کنید

هر Procedure باید پاسخ این سوال را داشته باشد:

از کجا بفهمیم کار درست انجام شده؟

مثلا در Deployment:

• Container running است؟
• Health Endpoint پاسخ می دهد؟
• Log خطای جدید ندارد؟
• Domain از بیرون پاسخ می دهد؟

از AI بخواهید برای هر مرحله Validation Point بسازد، اما فقط بر اساس معماری واقعی شما.

Rollback را فراموش نکنید

مستندی که فقط مسیر Forward را توضیح می دهد ناقص است.

Prompt مفید:

برای هر تغییر State-changing که در Procedure وجود دارد، یک Rollback Step اضافه کن.
اگر Rollback از اطلاعات من مشخص نیست، به جای حدس عبارت «Rollback نیاز به تعریف دارد» بنویس.

همین جمله می تواند Gapهای مهم عملیات را آشکار کند.

اطلاعات حساس را وارد مستند نکنید

مستند خوب نباید تبدیل به Secret Store شود.

از درج این موارد خودداری کنید:

• Password واقعی
• API Key
• Token
• Private Key
• Recovery Code

به جای آن بنویسید:

Credential از Secret Manager با نام prod/db/app دریافت شود.

یعنی محل دسترسی را مستند کنید، نه خود Secret را.

یک Prompt آماده برای Runbook

یادداشت های خام زیر را به Runbook عملیاتی تبدیل کن.

مخاطب: مهندس فنی که با این سیستم آشنا نیست.

ساختار:

• هدف
• Scope
• پیش نیازها
• مراحل
• Validation
• Rollback
• خطرها و هشدارها
• اطلاعاتی که هنوز ناقص است

قوانین:

• هیچ IP، Command، مسیر یا Credential جدید نساز.
• اگر داده ای وجود ندارد بنویس «نامشخص».
• مراحل را کوتاه و اجرایی بنویس.

یادداشت ها:
...

AI را برای Review مستند هم استفاده کنید

بعد از نوشتن، می توانید نقش مدل را عوض کنید:

این Runbook را مثل یک مهندس On-call که ساعت 3 صبح آن را برای اولین بار می خواند بررسی کن.
موارد مبهم، ترتیب اشتباه، مرحله بدون Validation و Rollback ناقص را مشخص کن.

این نوع Review معمولا از درخواست ساده «بهترش کن» مفیدتر است.

مستند خوب زنده است

اگر Procedure تغییر کرد ولی مستند همان نسخه قدیمی ماند، مستند می تواند خطرناک تر از نبود مستند باشد.

بنابراین برای مستندهای مهم این اطلاعات را نگه دارید:

• Owner
• Last Reviewed Date
• Version یا Revision
• ارتباط با Repo یا Config
• تاریخ تغییر بزرگ بعدی

AI می تواند نوشتن را سریع کند، اما فرایند Update و Ownership هنوز باید در تیم تعریف شود.

جمع بندی

هوش مصنوعی می تواند هزینه زمانی مستندسازی را به شدت کم کند، چون لازم نیست از صفحه سفید شروع کنید.

شما شواهد و اطلاعات واقعی را می دهید و AI آنها را سازمان دهی می کند.

مدل خوب استفاده این است:

Raw Notes → Structured Draft → Human Verification → Operational Document

هدف این نیست که مستند بیشتری تولید کنید.

هدف این است که دفعه بعد که مشکلی پیش آمد، یک نفر بتواند در چند دقیقه بفهمد:

چه چیزی داریم، چه کاری باید انجام دهد، چطور صحت آن را بررسی کند و اگر خراب شد چطور برگردد.