رایج است که پس از برطرف کردن یک باگ پیچیده، تیم توسعه یا فردی در اطراف آن‌ها ایده‌ای مطرح کند مبنی بر اینکه “باید بیشتر مستندسازی کنیم”. اگر توضیحی را که از ابتدا مانع از ایجاد این سردرگمی می‌شد مستندسازی کرده بودیم، این مشکل هرگز به وجود نمی‌آمد! البته، این حرف از دیدگاه گذشته‌نگر آسان است، اما گذشته‌نگری در پیشگیری از مشکلات چندان مفید نیست. آیا می‌توانیم پیش از بروز مشکلات بدانیم چه چیزی را مستندسازی کنیم؟ در این مطلب، بررسی خواهم کرد که چرا مستندسازی خوب چالش‌برانگیز است و راهکارهایی ارائه می‌کنم که بتوانید این کار را مؤثر انجام دهید بدون آنکه تمام وقت خود را صرف آن کنید.
برای درک مستندسازی، باید ارتباطات را درک کنیم. و برای درک ارتباطات، باید اطلاعات را بشناسیم. واضح است که اطلاعات مفهومی اساسی در فناوری اطلاعات (Information Technology) هستند. در ادبیات، اطلاعات به‌عنوان داده‌ای با ساختار مشخص که هدف یا معنایی دارد تعریف می‌شود. مفهومی مرتبط به آن، دانش است که کمی متفاوت است: اطلاعات درونی‌شده که می‌تواند برای تصمیم‌گیری استفاده شود.
درحالی‌که اطلاعات عمدتاً عینی است، دانش در ذهن ایجاد می‌شود و برای هر ذهن متفاوت خواهد بود. به‌عنوان‌مثال، یک پیش‌بینی آب‌وهوا با دمای ۲۰ درجه سانتی‌گراد و آفتابی برای افراد از مناطق مختلف آب‌وهوایی معانی متفاوتی خواهد داشت: فردی هلندی مثل من ممکن است بدون کت از خانه خارج شود، درحالی‌که یک ایتالیایی قطعاً یک ژاکت با خود می‌آورد. یک اطلاعات مشابه می‌تواند بر اساس دانش موجود منجر به تصمیمات مختلف شود. این دانش می‌تواند بر اساس محل تولد، حرفه، سن، محیط و بسیاری عوامل دیگر کسب شود.
ارتباطات تبادل اطلاعات است. این مسئله یک چالش اساسی ایجاد می‌کند: ارتباطات تبادل مستقیم دانش نیست. بلکه اگر بخواهیم دانش خود را به اشتراک بگذاریم، باید یک قطعه اطلاعات از آن خلق کنیم و آن را به گیرنده منتقل کنیم، که سپس این اطلاعات را با مغز خود تفسیر کرده و از آن دانش جدیدی بسازد. حتی بدتر، اگر بخواهیم بفهمیم آیا ارتباط ما تأثیر مورد نظر را داشته است، گیرنده باید یک قطعه اطلاعات بسازد که دانش خود را توصیف کند و آن را به ما بازگرداند.
ارتباطات به اشکال مختلف وجود دارد: شفاهی یا کتبی، یک‌به‌یک یا یک‌به‌چند، هم‌زمان یا غیرهم‌زمان. هر شکل مزایا و معایب خود را دارد. شکلی که اغلب هنگام توصیف نرم‌افزار ترجیح داده می‌شود، کتبی، یک‌به‌چند و غیرهم‌زمان است. پر کردن صفحات ویکی که دیگران می‌توانند بعداً برای درک چگونگی عملکرد و دلیل آن به آن‌ها رجوع کنند. این نوع ارتباط کتبی، غیرهم‌زمان و یک‌به‌چند همان چیزی است که مستندسازی نامیده می‌شود. هرچند که دلیل استفاده از این شکل ارتباط قابل‌توجیه است، اما این نسخه همان‌جایی است که درک‌های مختلف می‌تواند بدون آگاهی فوری فرستنده یا گیرنده رخ دهد (به دلیل ماهیت غیرهم‌زمان).
به‌طور کلی، همه موافق‌اند که مستندسازی سیستم باید وجود داشته باشد. وارد شدن به سیستمی بدون هیچ مستندی به این معناست که شما باید از طریق کنترل‌ها و کد بفهمید سیستم چه می‌کند. درحالی‌که کد واضح و بدون ابهام است، همیشه نحوه رفتار آن آشکار نیست.
اما چه چیزی را باید مستندسازی کنیم و در چه سطحی؟ ما نمی‌توانیم همه چیز را به همه روش‌های ممکن مستندسازی کنیم، زیرا (۱) زمان صرف‌شده برای مستندسازی، زمانی را می‌گیرد که می‌توانست صرف توسعه شود، و (۲) یک حجم عظیم مستندات در واقع پیدا کردن پاسخ‌های موردنظر را سخت‌تر می‌کند. ما کوچک‌ترین مقدار ممکن مستندات را می‌خواهیم که بتواند بیشترین تعداد سؤالات را پاسخ دهد، به گونه‌ای که به‌راحتی قابل به‌روزرسانی باشد. علاوه بر این، باید به گونه‌ای باشد که برای تمام ذینفعان بدون توضیح اضافی قابل‌تفسیر باشد.
این ممکن است آشنا به نظر برسد: چالش‌هایی که برای مستندسازی داریم بسیار شبیه به چالش‌هایی است که برای کد داریم. ما نمی‌دانیم خوانندگان چگونه به مستندات پاسخ خواهند داد، نمی‌دانیم دقیقاً چه چیزی را از قبل نیاز دارند، و نمی‌دانیم آیا ساختار مستندسازی فعلی بهترین ساختار برای آینده نیز خواهد بود. خوشبختانه، این به این معناست که می‌توانیم از برخی تکنیک‌ها برای مقابله با چالش مستندسازی نیز استفاده کنیم. من سه راهبردی را که خودم برای مستندسازی کمتر و در عین حال توضیح بهتر استفاده می‌کنم، با شما به اشتراک خواهم گذاشت.
۱. برای خواننده (و نیازهای او) بنویسید
شما نمی‌توانید با مستندسازی خود به همه در هر موردی کمک کنید، اما می‌توانید تلاش کنید تا بفهمید چه کسانی و به چه دلیلی آن را می‌خوانند. اگر برای کاربران یک برنامه مستندسازی می‌کنید، به زبان ساده توضیح دهید که با این برنامه چه کارهایی می‌توانند انجام دهند. هنگام نوشتن برای توسعه‌دهندگان، به سؤالاتی پاسخ دهید که از کد به‌وضوح مشخص نیستند. کد منبع خوبی برای توسعه‌دهندگان است، و مستندسازی چیزی که کد به‌خوبی توضیح می‌دهد، تنها اتلاف وقت است. البته، اینکه چه چیزی برای توسعه‌دهندگان واضح است، بهتر است خود آن‌ها قضاوت کنند.
۲. روی یک پایه‌ی ثابت سرمایه‌گذاری کنید
سیستمی که موضوع مستندسازی است ممکن است در حال توسعه فعال باشد، اما پایه آن باید نسبتاً ثابت باشد. اگر این‌گونه است، مطمئن شوید که آن را با دقت مستندسازی کنید. درک پایه‌ای که موضوع شما بر آن ساخته شده است، فهم استدلال‌های شما را آسان‌تر می‌کند. از تجربه من به‌عنوان تحلیلگر کسب‌وکار، یک مدل دامنه خوب که روابط بین اشیاء دامنه را ثبت می‌کند، بسیار مفید است تا افراد موضوع تحت پوشش سیستم را بهتر درک کنند. این مدل به کارشناسان دامنه و توسعه‌دهندگان امکان می‌دهد که با یکدیگر درباره موضوع سیستم شما بحث کنند. از نظر فناوری، مستندسازی معماری راه‌حل (به‌عنوان‌مثال با استفاده از مدل C4) یا استفاده از سوابق تصمیمات معماری (Architectural Decision Records) می‌تواند به توسعه‌دهندگان درک سریعی از نحوه تنظیم راه‌حل ارائه دهد.
۳. هر از گاهی بازنگری کنید
هنگام ایجاد چیزی در طول زمان، به‌راحتی می‌توان در کارهای روزمره غرق شد و تصویر کلی را فراموش کرد. همان‌طور که سیستم‌ها و برنامه‌ها نیاز به بازبینی دارند، برای مستندسازی خود نیز هر از گاهی وقت بگذارید تا اهداف آن را بسنجید و بررسی کنید که آیا همه آن هنوز برای آن اهداف ضروری است. از حذف مستنداتی که دیگر مهم نیستند یا می‌توانند به‌طور مؤثرتری نوشته شوند، نترسید. چالش این است که مستندسازی را ساده نگه دارید، همان‌طور که در مطلب من درباره «سادگی عمدی» توضیح داده شده است.
افرادی که در توسعه نرم‌افزار فعالیت می‌کنند متوجه می‌شوند که این راهبردها برای مستندسازی، همچنین شیوه‌های خوبی برای ایجاد نرم‌افزار هستند. این شباهت منطقی است: مستندات سیستم، همانند خود سیستم، یک اثر هنری است و چرخه عمر مشابهی دارد. عالی می‌شد اگر می‌توانستیم بهترین ساختار مستندسازی را از ابتدا بدانیم، اما نمی‌توانیم؛ تنها می‌توانیم با توجه به آنچه اکنون می‌دانیم، بهترین کار ممکن را انجام دهیم.
علاوه بر این راهبردها، باید به این نکته توجه کنیم که درک از طرق مختلف حاصل می‌شود، بنابراین مستندسازی را به‌عنوان تنها راه‌حل در نظر نگیرید. بهترین راه برای اعتبارسنجی درک، استفاده از مثلث‌بندی است: جمع‌آوری شواهد از منابع مختلف. یک توضیح صوتی برای پاسخ دادن به سؤالاتی که مستندسازی ایجاد می‌کند، می‌تواند تفاوت بزرگی ایجاد کند. مسیر دستیابی به مستندسازی «کامل» طولانی و ارزش هزینه آن را ندارد، اما نداشتن مستندسازی به‌طور کامل منجر به سردرگمی بیشتری در آینده خواهد شد. مستندسازی اطلاعاتی است که به ساخت دانش کمک می‌کند، اما در دام این تصور نیفتید که داشتن مستندات خوب به‌تنهایی کافی است.
در نهایت، هدف مستندسازی نباید پوشش دادن هر جزئیات ممکن باشد، بلکه ایجاد تعادل بین شفافیت و عملی بودن است. با استفاده از این راهبردها – تمرکز بر خواننده، مستندسازی پایه‌ی ثابت و بازنگری دوره‌ای – مستنداتی ایجاد کنید که هم مفید باشد و هم قابل مدیریت، تا تیم شما بدون گرفتار شدن در دام مستندسازی، بهره‌وری خود را حفظ کند.