از مستندسازی متنفرم. تا همین چندوقت پیش تجربه‌هایم در مستندسازی محدود می‌شد به تکالیف دانشگاهی. در آن تکالیف ما را مجبور می‌کردند تا برای برنامه‌هایمان مستندسازی کنیم. من همیشه در پایان کار چند خط اطلاعات به‌دردنخور می‌نوشتم و همراه برنامه‌هایم می‌فرستادم. با شروع کار در سارینا برای آنکه از عهده‌ی مسئولیت‌های جدید بربیایم، رجوع به یکی دو مستند حسابی کارم را راه انداخت. بعد از آن بود که سعی کردم بر نفرتم به مستندسازی غلبه کنم و ببینم چطور می‌توانم خودم هم مستنداتی این‌چنینی بنویسم. می‌دانم که نفرتم زیاده‌روی است و شاید دلیلش تکالیف اجباری دانشگاه باشد اما تا آنجا که می‌دانم فقط من نیستم که مستندسازی را دوست ندارم. اکثر برنامه‌نویس‌ها همین‌طورند به‌خصوص اگر در گروهی باشند که پروژه‌ها با رویکرد اجایل و اسکرام انجام می‌شوند. این تمایل البته غیرمنطقی هم نیست. در بیانیه‌ی توسعه‌ی نرم‌افزار چابک هم آمده که نرم‌افزاری که کار می‌کند از مستندسازی جامع بهتر است؛ اما آیا این بهتر بودن به این معنا است که دور مستندسازی را کاملاً خط بکشیم؟ مسلماً نه اما برای مستندسازی باید چه‌کار کنیم؟ بگذارید بهتر بپرسم: چرا، چه‌وقت، چه‌چیز را، چقدر و چگونه مستندسازی کنیم؟ پاسخ به این پنج سوال تا حد زیادی بستگی به ویژگی‌ها، کار و تیم شما دارد. برای آنکه این عوامل را در نظر بگیریم، در ادامه سعی می‌کنم این پنج سوال را به سوال‌های بیشتر و واضح‌تر بشکنم. فرض بر این است که از اجایل استفاده می‌کنیم و همچنین اینجا منظور از مستندسازی، قسمت فنی است که مخاطبش توسعه‌دهنده است و شامل مستندهای راهنما برای کاربران نرم‌افزار و نیز مستندهای بازاریابی نمی‌شود.
مستندسازی چه بدی دارد؟
بدترین چیز مستند این است که استاتیک است؛ به این معنا که هر اتفاقی که در نرم‌افزار می‌افتد همانطور سر جای خودش می‌ماند و قدیمی می‌شود و ممکن است اطلاعاتش تبدیل به اطلاعاتی بی‌فایده یا حتی گمراه‌کننده شود. به‌روزرسانی مستندها؟ مصیبت است. در کل مستندها معمولاً در برابر زمان زیادی که می‌گیرند، فایده‌ی کمی می‌رسانند.
مستندسازی به چه درد می‌خورد؟
مهم‌ترین فایده‌ی مستندسازی این است که باعث می‌شود کمتر سرمان را به دیوار بکوبیم. مستندی که درست و به‌جا نوشته شده باشد، از اشتباه‌های مهلک پیشگیری می‌کند. در ضمن در یادگیری و انتقال دانش بین اعضای تیم نیز موثر است.
چقدر فراموش‌کارید؟ چقدر اشتباه می‌کنید؟
اگر شما هم مثل من یادتان رفته امروز چه غذایی خورده‌اید و یا چیزی در جلوی چشمتان هست و دنبالش می‌گردید، به احتمال زیاد به مستندسازی نیاز دارید. مستندسازی از گیج خوردن و فراموشی جلوگیری می‌کند.
تیم چگونه است؟ ساختار روابط چگونه است؟
جایگاه شما در سازمان و همچنین شکل روابطتان با دیگر اعضا مهم است. چقدر می‌توانید با همکارتان گفتگو کنید؟ چقدر از هم شناخت دارید؟ اگر صمیمی هستید و یا مثلا با خواهر/برادر خود همکارید، احتمالا نیازی به مستندسازی برای یکدیگر ندارید.
زمان حضور شما در سازمان و شکل همکاری شما نیز اهمیت دارد. اگر معمولا در دسترس نیستید و یا مدت‌زمان همکاریتان کوتاه است، به احتمال قوی مستندسازی لازم است.
اندازه‌ی تیم چقدر است؟ کار بین چه تعداد افرادی مشترک است؟
اندازه‌ی گروه و کار هر چه بزرگ‌تر باشد، بیشتر به مستندسازی نیاز داریم. مستندسازی می‌تواند در انتقال دانش موثر باشد. همچنین در مواقعی که یک کار خاص بین افراد مشترک است، مستندسازی کمک می‌کند تا عضو تازه‌کار کمتر اشتباه کند و زمان کمتری صرف پیدا کردن راه‌حل کند.
آیا کار گام به گام است؟ چقدر کار تکرار می‌شود؟
برایم پیش آمده که در اجرای فرآیندی که بارها و بارها آن را انجام می‌دهم، یکی از گام‌های فرآیند را فراموش می‌کنم و در آخر از به نتیجه نرسیدن فرآیند درمانده می‌شوم و زمان زیادی را از دست می‌دهم. در چنین مواقعی رجوع به مستندی که حتی خیلی خلاصه به گام‌های فرآیند اشاره کرده باشد، از اشتباه پیشگیری می‌کند. به طور معمول در فرآیندهای گام‌به‌گامی که امکان تکرار آن وجود دارد، اگر تعداد گام‌ها زیاد است و به‌خصوص ترتیب اجرای گام‌ها اهمیت دارد، به مستندسازی نیاز داریم.
حساسیت کار چقدر است؟ پویایی کار چطور؟
هر چه هزینه‌ی اشتباه در کار بالاتر باشد، بیشتر به مستندسازی نیازمندیم. گاهی صرف زمان زیاد در مستندسازی برای پیشگیری از یک اشتباه جبران‌ناپذیر می‌ارزد. باید توجه کنیم که این در شرایطی که کار پویا است و مدام تغییر می‌کند، نتیجه‌ی عکس دارد. ممکن است رجوع به مستندی قدیمی که قبل از تغییرات در کار نوشته شده باعث اشتباه در یک کار حساس شود. در چنین مواقعی باید به جای فرآیندها، تغییرات فرآیندها را مستند کنیم (changelog).
پیچیدگی کار چقدر است؟
یک موقعیت جالب در مستندسازی هنگامی است که کاری پیچیده را مستند می‌کنیم. ممکن است کل زمانی که برای فهمیدن کاری پیچیده در مواقع رجوع به آن کار صرف می‌کنیم از کل زمانی که آن کار پیچیده را تنها یک‌بار با مستندسازی قابل‌فهم می‌کنیم، کمتر شود. در چنین موقعیت‌هایی مستندسازی در بلندمدت زمان را برایمان می‌خرد. موقعیت مشابه دیگر، هنگامی است که در کاری به مشکلات عجیب و غریب می‌خوریم و به جز آنکه ممکن است کارمان به بیمارستان و تیمارستان بکشد، زمان زیادی را صرف می‌کنیم تا از این مشکلات عبور کنیم. تصور این که در آینده دوباره دنبال راه حل چنین مشکلاتی بگردیم، زجرآور است. بهتر است بدبختی‌هایمان را مستند کنیم تا از یک سوراخ دوبار گزیده نشویم.
چه چیز را مستند کنیم؟
مستندسازی فنی شامل مستندسازی برای معماری سیستم، کدها، پیش‌نیازها و فرآیندهای نصب، اجرا و نگهداری می‌شود. البته در اجایل معمولاً به مستندسازی برای کدها نیاز نداریم و آنچه که اهمیت دارد صحت، تمیزی و شیوایی کدها است و بهتر است در صورت لزوم کامنت بگذاریم.
چگونه و چطور مستند کنیم؟
بدترین کار این است که مستندسازی را به بعد از اتمام کار موکول کنیم. بهترین زمان برای مستندسازی درست لحظه‌ای است که تشخیص می‌دهید چیزی باید مستند شود. تنبلی نکنید و هم‌زمان با کار چیزهایی را که ارزش نوشتن دارند، مستند کنید. چطور؟ از مارک‌داون استفاده کنید. گذاشتن یک فایل readme درون ریپازیتوری‌ها جای دوری نمی‌رود. تا دلتان بخواهد قالب‌ها و جنریتورهای مختلف برای انواع و اقسام مستندسازی‌ها وجود دارد. ممکن است در یک سازمان کوچک کمتر به مستندسازی نیاز داشته باشیم و با چند فایل در گوگل‌داکس کارمان راه بیفتد و ممکن است درگیر پروژه‌ای بزرگ باشیم و حجم بالای مستندات ما را به استفاده از برنامه‌های ویکی متقاعد کند. در هر صورت برای مستند کردن یا نکردن هیچ قانون کلی نداریم و برای تصمیم‌گیری در هر مورد باید سود و زیان مستندسازی را با توجه به شرایط بسنجیم و از تجربه‌های قبلی استفاده کنیم.
این‌ها سوالاتی بود که برای مستندسازی در یک سازمان ذهن مرا درگیر کرده بود. اما بیایید فکر کنیم همه با هم همکاریم. بیایید مشکل‌ها و راه‌حل‌ها و ابتکارهایمان را با هم به اشتراک بگذاریم. می‌توانیم مستندات باارزشمان را آنلاین کنیم و یا حتی از همان اول آنلاین مستندسازی کنیم مثلا در یک پست وبلاگ، چند خط توضیح در یک صفحه روی گیت‌هاب و یا یک پاسخ در استک اورفلو. الان دیگر تصور اینکه بدون استک اورفلو چگونه مشکلاتمان را حل می‌کردیم دشوار است. دیگر کمتر پیش می‌آید که بخواهیم چیزی را بدانیم یا یاد بگیریم و روی وب پیدایش نکنیم. در مورد موضوع خودمان می‌توانید مطلب مفصلی درباره‌ی استراتژی‌های مستندسازی اجایل را در اینجا و best practiceها برای مستندسازی اجایل را در اینجا ببینید. اگر شما هم در این مورد تجربه یا نظری دارید، با ما در میان بگذارید.
