مستندسازی نرمافزار سازمانی
مستندسازی یکی از آن کارهایی است که همه موافقشاند و کمتر کسی انجامش میدهد. و جالب اینکه هر دو طرف حق دارند.
طرفی که میگوید «باید مستند داشته باشیم» درست میگوید: تیم عوض میشود، پیمانکار عوض میشود، و دانشی که فقط در سر آدمهاست با آنها میرود.
طرفی که مستند نمینویسد هم بیدلیل نیست: بیشتر مستندهایی که در پروژهها نوشته میشوند، دو ماه بعد غلطاند و مستند غلط از نبودِ مستند بدتر است، چون کسی به آن اعتماد میکند.
پس سؤال درست این نیست که «مستند بنویسیم یا نه». این است که چه چیزی را بنویسیم که کهنه نشود.
معیاری که همهچیز را ساده میکند
مستند خوب، چیزی را ثبت میکند که از کد قابل استخراج نیست.
اینکه این تابع چه پارامتری میگیرد، در خود کد نوشته شده و بهتر از هر مستندی بهروز است. اینکه این جدول چه ستونهایی دارد، در اسکیما هست.
آنچه در کد نیست:
- چرا این تصمیم گرفته شد و چه گزینههایی رد شدند.
- قواعد کسبوکاری که از بیرون آمدهاند — قانون، بخشنامه، توافق با مشتری.
- اتصالهای بیرونی و رفتار عجیبشان.
- کارهایی که یک بار در سال انجام میشوند و کسی یادش نمیماند.
هر جملهای که بنویسید و از کد قابل خواندن باشد، بدهی است نه دارایی. نگهداری لازم دارد و ارزشی اضافه نمیکند.
چهار نوع مستند و مخاطبشان
یک: تصمیمهای معماری
کوتاهترین و باارزشترین. برای هر تصمیم مهم، یک صفحه: مسئله چه بود، چه گزینههایی داشتیم، چه انتخاب کردیم، چرا، و چه چیزی را با این انتخاب از دست دادیم.
اینها کهنه نمیشوند چون تاریخدارند. تصمیم سال ۱۴۰۳ در سال ۱۴۰۶ هم همان تصمیم است؛ ممکن است دیگر درست نباشد و همین که بدانید چرا گرفته شده، بازبینیاش را ممکن میکند.
اگر قرار است فقط یک نوع مستند داشته باشید، همین است. هزینهاش تقریباً هیچ است — نیم ساعت بعد از هر تصمیم مهم — و هیچ چیز دیگری جایش را نمیگیرد.
دو: نقشهٔ سامانه برای عضو جدید
یک سند که به کسی که تازه آمده میگوید سامانه از چه بخشهایی ساخته شده، هر بخش چهکار میکند، داده از کجا به کجا میرود، و برای راهاندازی محیط توسعه چه باید کرد.
معیار سلامتش هم روشن است: عضو جدید بتواند بدون پرسیدن، محیط را بالا بیاورد. اگر نتواند، سند غلط است.
نکتهٔ عملی: این سند را کسی بنویسد که تازه آمده، نه کسی که سه سال است هست. باتجربهها آنقدر چیزها را بدیهی میدانند که ننویسند.
سه: مستند رابط برنامهنویسی
اگر سامانهتان سرویسی به بیرون میدهد — به اپ موبایل، به پیمانکار دیگر، به سامانهٔ مشتری — این مستند اجباری است.
اما دستی ننویسیدش. از خود کد یا از تعریف OpenAPI تولید شود، وگرنه در اولین تغییر عقب میماند. آنچه دستی باید بنویسید فقط دو چیز است: نمونهٔ درخواست و پاسخ واقعی، و رفتار در حالت خطا.
آن مورد دوم همان جایی است که تقریباً همهٔ مستندهای رابط ناقصاند. هر کسی که با یک سرویس بیرونی کار کرده میداند سختترین بخش، فهمیدن این است که وقتی چیزی اشتباه پیش میرود، دقیقاً چه برمیگردد.
چهار: مستند کاربر
جدا از سه تای بالا و برای مخاطب دیگری. اینجا هم یک تفکیک لازم است: راهنمای «چطور این کار را انجام دهم» با راهنمای «این صفحه چه دکمههایی دارد» فرق دارد و اولی بیشتر خوانده میشود.
و صادقانه: در سامانههای سازمانی، ویدیوی کوتاه سهدقیقهای معمولاً از بیست صفحه متن مؤثرتر است. کاربر سازمانی متن نمیخواند؛ میخواهد ببیند چه کلیک میشود.
مستندی که نباید بنویسید
توضیح خطبهخط کد. اگر کد بدون توضیح فهمیده نمیشود، مشکل کد است. توضیح فقط جایی لازم است که کد کار غیرمنتظرهای میکند، و آنجا باید بگوید چرا، نه چه.
سند تحلیل و طراحی که بعد از شروع کد بهروز نمیشود. سندی که در فاز اول پروژه نوشته شده و شش ماه است دست نخورده، دیگر مستند نیست؛ سابقه است. اگر نگهش میدارید، تاریخش را روی جلدش بنویسید.
فهرست فیلدهای هر فرم. از رابط کاربری قابل دیدن است و با هر تغییر غلط میشود.
مستندسازی بهعنوان بند قرارداد
اگر کارفرمایید و پروژهای برونسپاری میکنید، این بخش را در قرارداد صریح کنید. «تحویل مستندات» بهتنهایی هیچ معنایی ندارد و معمولاً به یک PDF صد صفحهای ختم میشود که هیچکس نمیخواند.
چیزی که واقعاً بهکار میآید:
- راهنمای راهاندازی و استقرار، با معیار پذیرش روشن: تیم دیگری بتواند از صفر محیط را بالا بیاورد.
- فهرست اتصالهای بیرونی با اطلاعات دسترسی، محدودیتها و شخص پاسخگو.
- کارهای دورهای: پشتیبانگیری، بستن دوره، تمدید گواهی. همانهایی که سالی یک بارند و به همین دلیل فراموش میشوند.
- تصمیمهای معماری به همان شکل کوتاهی که بالا گفتیم.
- دسترسیها و مالکیت: دامنه، سرور، مخزن کد، حسابهای سرویس. این را در بند جدا بیاورید. تعداد سازمانهایی که مالک دامنهٔ خودشان نیستند و تازه در لحظهٔ اختلاف میفهمند، کم نیست.
معیار پذیرش را هم بنویسید: مستندی پذیرفته است که یک نفر بیرون از تیم اصلی بتواند با آن کار را انجام دهد. این تنها آزمون معتبر است.
چه کسی بنویسد و کِی
بهترین لحظه برای نوشتن، همان زمان تصمیمگیری است. یادداشت نیمساعته در لحظه، از سند سهروزهٔ شش ماه بعد کاملتر است، چون شش ماه بعد نصف دلایل یادتان نیست.
و مستند را کنار کد نگه دارید، در همان مخزن. سندی که در فضای ابری دیگری زندگی میکند، همراه کد تغییر نمیکند و همانجاست که واگرایی شروع میشود. اگر بهروزرسانی مستند بخشی از همان تغییری باشد که کد را عوض میکند، در بازبینی کد هم دیده میشود.
جمعبندی
مستند خوب کم است، خاص است، و کنار کد زندگی میکند. مستند بد، حجیم است، عمومی است، و در جای دیگری خاک میخورد.
اگر سامانهای دارید که دانشش در سر دو سه نفر است، شروع کوچک کنید: تصمیمهای معماری و راهنمای راهاندازی. این دو، بیشترین بخش ریسکی را پوشش میدهند که با رفتن یک نفر متوجهش میشوید — و در پشتیبانی هم اولین چیزی است که هنگام تحویلگرفتن سامانهای از تیم قبلی سراغش میرویم.