دربارهٔ این فصل
یادداشتِ همراه نوارتا حالا برایتان پیش آمده که روبه‌روی تکه‌ای از کد بنشینید و از خودتان بپرسید این تابع دقیقا چه کار می‌کند یا چرا این تصمیم عجیب در طراحی‌اش گرفته شده است؟ کمبود یا کهنگی مستندات یکی از رایج‌ترین گلایه‌های برنامه‌نویسان است، اما چه می‌شود اگر نگاه ما به نوشتن مستندات تغییر کند و آن را هم‌ردهٔ نوشتن خودِ کد بدانیم؟
در کتاب «مهندسی نرم‌افزار در گوگل» نوشتهٔ تیتوس وینترز، تام مانشریک و هایروم رایت، فصل دهم به موضوع مستندسازی اختصاص دارد و بررسی می‌کند که چطور می‌توان این بخش حیاتی را مقیاس‌پذیر کرد. مدیریت فرآیندها در مقیاس بزرگ برای تیم‌های نرم‌افزاری اهمیت زیادی دارد، به طوری که مهندسی نرم‌افزار (Software Engineering) یعنی ساختن و نگهداری نرم‌افزار در طول زمان، نه فقط نوشتن کدهای اولیه.
یکی از مشکلات بزرگ تیم‌ها این است که مستندات را جدا از چرخهٔ توسعه نگه می‌دارند. وقتی مستندات در یک سامانهٔ ویکی جداگانه رها شوند، به مرور منسوخ شده و گم می‌شوند. راه حل این است که مستندات را درست مانند کد، داخل کنترل نسخه قرار دهیم تا با تغییر هر بخش از کد، مستندات مربوط به آن هم بازبینی و به‌روز شوند.
بسیاری از برنامه‌نویسان گمان می‌کنند مهارت نوشتن با برنامه‌نویسی کاملاً متفاوت است و آن‌ها نویسندگان خوبی نیستند. اما حقیقت این است که نوشتن مستندات خوب نیاز به ادبیات پیچیده ندارد، بلکه نیازمند درک نیاز مخاطب است؛ دقیقاً مثل فرآیند بازبینی کد (Code Review) که در آن بررسی تغییرات کد توسط همکاران پیش از ادغام انجام می‌شود تا کیفیت کار بالا بماند.
مشکل دیگر این است که مستندات معمولاً تنها برای خودِ نویسنده یا بر اساس فرض‌های ذهنی او نوشته می‌شوند. نویسنده ممکن است جزئیات فنی را از زاویهٔ دید خودش بدیهی بداند، در حالی که یک کاربر تازه یا فردی از تیمی دیگر کاملاً سردرگم شود. راه حل این است که مخاطب خود را بشناسیم و مستندات را کوتاه‌تر، شفاف‌تر و متمرکز بر یک هدف مشخص نگه داریم.
برای نمونه، وقتی یک مستند مرجع می‌نویسیم، باید فرض کنیم مخاطب فردی است که می‌داند چه می‌خواهد و فقط به دنبال ساختار مشخصی می‌گردد. در مقابل، اگر در حال نوشتن یک آموزش یا راهنمای شروع به کار هستیم، باید گام‌ها را صریح و به ترتیب شماره‌گذاری کنیم تا خواننده در قدم چهارم دچار خطا نشود.
از نظر من، بهترین راه این است که نوشتن مستندات را نه یک بار اضافه‌ی کاری، بلکه بخشی از وظیفهٔ روزمرهٔ خود بدانیم و برای کدهایی که قرار است بیش از چند ماه عمر کنند، وقت بگذاریم. مستندسازی خوب شاید در روزهای اول زمان‌بر باشد، اما در بلندمدت هزینه‌های نگهداری سیستم را به شدت کاهش می‌دهد.
پس دفعهٔ بعد که کدی را توسعه می‌دهید، پیش از بستن تغییرات، چند خطی هم برای آگاهی نفر بعدی که قرار است سراغ آن بیاید بنویسید. این کار کوچک، بخش بزرگی از اصطکاک تیم را از بین خواهد برد.