نوشتن مستندات فنی که واقعاً خوانده شود
همه میدانند مستندات لازم است و تقریباً هیچکس نمینویسد. دلیلش تنبلی نیست — نبود روش است. این مقاله روشی میدهد که با کمک هوش مصنوعی قابل اجراست.
یک فایل README را باز میکنید. مینویسد: «برای نصب، دستور نصب را اجرا کنید.» تمام. توسعهدهندهی تازهوارد بعد از پنج دقیقه صفحه را میبندد و میرود از همکار بغلدستیاش میپرسد.
این صحنه در بیشتر تیمها تکرار میشود، و دلیلش تنبلی نیست. مستندنویسی یک مهارت جداست که کسی آموزشش را ندیده، و در فشار ددلاین اولین چیزی است که حذف میشود.
هوش مصنوعی این معادله را عوض کرده — نه چون بهتر از شما مینویسد، چون هزینهی شروع را تقریباً صفر کرده. تفاوت بین «هیچ مستندی نداریم» و «یک پیشنویس داریم که باید اصلاح شود» خیلی بزرگ است.
چرا مستندات خوانده نمیشود
سه اشتباه ساختاری تکرار میشود. اول، همهچیز در یک فایل: آموزش مبتدی، مرجع فنی و بحث معماری کنار هم. کسی که دنبال یک پارامتر میگردد باید سه صفحه رد کند.
دوم، نوشتن از دید کسی که همهچیز را میداند. جملهی «کافی است سرویس را به میکروسرویس احراز هویت وصل کنید» برای نویسنده روشن است و برای خواننده هیچ معنایی ندارد.
سوم، نبود مثال اجراپذیر. هر مستندی که یک نمونهی کامل و قابل کپی ندارد، در عمل نیمهتمام است.
چهار نوع مستند را قاطی نکنید
این تفکیک بیشتر از هر تکنیک دیگری کیفیت را بالا میبرد:
- آموزش — برای کسی که هیچچیز نمیداند. هدف: یک بار موفق شدن، حتی اگر همهچیز را نفهمد.
- راهنمای گامبهگام — برای کسی که کار مشخصی دارد. «چطور یک وبهوک اضافه کنم».
- مرجع — فهرست خشک و کامل. پارامتر، نوع، مقدار پیشفرض، خطاها.
- توضیح — چرایی. چرا این معماری انتخاب شد و چه چیزی را فدا کرد.
چارچوب Diátaxis همین تقسیمبندی را دقیقتر توضیح میدهد و در بسیاری از پروژههای بزرگ متنباز پایهی ساختار مستندات است.
قبل از نوشتن هر بخش، از خودتان بپرسید خواننده در آن لحظه چه چیزی میخواهد: یاد بگیرد، کاری را انجام بدهد، چیزی را پیدا کند، یا بفهمد چرا؟ اگر جواب بیش از یکی است، بخش را بشکنید.
تولید مستند مرجع از روی کد
این جایی است که بیشترین صرفهجویی اتفاق میافتد. کد را بدهید و دقیق بگویید چه ساختاری میخواهید:
برای این کد مستند مرجع بنویس.
برای هر تابع عمومی:
- یک جمله که میگوید چه کار میکند (با فعل شروع کن)
- پارامترها: نام، نوع، اجباری یا اختیاری، مقدار پیشفرض
- خروجی و نوعش
- خطاهایی که ممکن است پرتاب شود و در چه شرایطی
- یک مثال کوتاه اجراپذیر
قواعد:
- توابع داخلی و خصوصی را نادیده بگیر
- چیزی ننویس که در کد نیست؛ اگر رفتاری مبهم است،
زیرش بنویس «نیاز به بررسی»
- خروجی مارکداون
---
[کد]آن جملهی «چیزی ننویس که در کد نیست» ضروری است. بدون آن، مدل رفتارهای منطقی ولی نادرست را حدس میزند و شما مستندی میگیرید که دروغ میگوید — بدتر از نداشتن مستند.
README که کار میکند
ترتیب اهمیت دارد، چون بیشتر خوانندهها فقط بخش اول را میبینند:
- یک جمله: این پروژه چه مشکلی را حل میکند.
- پیشنیازها با نسخهی دقیق.
- نصب و اجرا — دستورها بهترتیب، بدون مرحلهی نانوشته.
- یک مثال کامل که خروجیاش هم نشان داده شده.
- تنظیمات و متغیرهای محیطی.
- مشکلات رایج و پیامشان.
بند ششم بیشترین ارزش را دارد و کمترین توجه را میگیرد. هر خطایی که تازهواردها بیش از یک بار گرفتهاند، باید عین متن خطا و راهحلش آنجا باشد — چون آدمها همان متن را جستجو میکنند.
چه چیزی را بسپارید
| بخش | هوش مصنوعی | شما |
|---|---|---|
| مرجع API | پیشنویس کامل | بازبینی صحت |
| راهنمای گامبهگام | ساختار و نگارش | مراحل واقعی |
| مثال کد | نسخهی اولیه | اجرا و تأیید |
| پیامهای خطا و رفعشان | مرتبکردن | فهرست واقعی از تجربه |
| دلیل تصمیم معماری | هیچ | همهاش |
| ترجمهی مستند به انگلیسی | تقریباً کامل | اصطلاحات دامنه |
چیزی که هیچ ابزاری نمیتواند بنویسد
مهمترین مستند هر پروژه معمولاً کوتاهترین است: چرا اینطور ساخته شد. چرا صف را انتخاب کردید و نه فراخوانی مستقیم؟ چرا آن جدول ایندکس ندارد؟
این اطلاعات در کد نیست — در جلسهای بود که شش ماه پیش برگزار شد. یک فایل ساده با فهرست تصمیمها بسازید: تاریخ، تصمیم، گزینههای رد شده، دلیل. سه خط برای هر تصمیم کافی است و همین سه خط، سال بعد یک بازنویسی بیمورد را جلوگیری میکند.
بهروز نگهداشتن
مستند غلط بدتر از مستند نبودن است، چون خواننده به آن اعتماد میکند. دو عادت ساده این را حل میکند: مستندات را در همان مخزن کد نگه دارید، و در چکلیست بازبینی کد یک سطر اضافه کنید که میپرسد آیا رفتار عوض شده و مستندش هم عوض شده است.
اگر با ابزارهای کمککدنویسی کار میکنید، تولید پیشنویس تغییرات مستند را میشود به همان مسیر اضافه کرد؛ روش کلیاش در هوش مصنوعی برای برنامهنویسی آمده.
جمعبندی
مستندات خوب سه ویژگی دارد: میدانید هر بخش برای چه کسی است، هر ادعایی مثال اجراپذیر دارد، و کنار کد زندگی میکند. هوش مصنوعی هر سه را ارزانتر کرده ولی هیچکدام را خودکار نکرده — نقشش تولید پیشنویس است، نه تصمیمگیری دربارهی ساختار.
برای شروع، پرزحمتترین بخش پروژهتان را انتخاب کنید و همان پرامپت مرجع را در نارنگی اجرا کنید. اصول نوشتن پرامپت دقیق را هم در راهنمای پرامپتنویسی ببینید. جامعهی Write the Docs منابع خوبی برای عمیقتر شدن دارد.
مطالب مرتبط:
