مستنداتی که بیصدا کهنه میشوند
نبود مستندات، مشکل شناختهشدهای است. همه میدانند بد است و همه میدانند چرا.
مشکل کمتر شناختهشده این است: سندی که یک بار درست بوده و حالا نیست، از نبودِ سند بدتر است.
چون کسی که سند ندارد، میپرسد یا بررسی میکند. کسی که سند دارد، به آن اعتماد میکند — و بر اساس چیزی تصمیم میگیرد که دو سال پیش درست بوده.
چرا این اتفاق حتماً میافتد
سند در لحظهای نوشته میشود که همهچیز روشن است. بعد کد عوض میشود، نسخه بالا میرود، سرور جابهجا میشود، و هیچکدام از این تغییرها به سند خبر نمیدهند.
این نه بینظمی است و نه قابل رفع با «یادآوری بیشتر». ذاتی است: سند و واقعیت دو چیز جدا هستند که فقط با کار مستمر همراستا میمانند.
پس بهجای تلاش برای اینکه سند هیچوقت کهنه نشود — که نشدنی است — باید کاری کرد که کهنه بودنش قابل تشخیص باشد.
سه کاری که این را ممکن میکند
۱. هر ادعا تاریخ دارد
نه تاریخ آخرین ویرایش فایل. تاریخ خود ادعا.
«نسخهٔ X روی این سرویس اجرا میشود» ← بیفایده
«نسخهٔ X، بررسیشده در تاریخ Y» ← قابل قضاوت
خوانندهای که تاریخ را میبیند، خودش میفهمد باید اعتماد کند یا دوباره بررسی کند. همین یک تغییر، بیشترین اثر را در کل این فهرست دارد.
۲. «تأییدشده» از «فرضشده» جدا میشود
در هر سندی، دو جنس جمله وجود دارد و معمولاً از هم قابل تفکیک نیستند:
- چیزی که کسی واقعاً دیده و امتحان کرده
- چیزی که منطقی به نظر میرسد و کسی بررسیاش نکرده
دومی اکثریت است و همان است که در بحران غافلگیر میکند: «فکر میکردیم پشتیبانگیری کار میکند» جملهای است که فقط بعد از حادثه گفته میشود.
پس در سند علامتشان بزنید. یک نشانهٔ ساده کافی است — و هر چیزی که فرض است، یک کار باز است نه یک واقعیت.
۳. سند، عکسی از یک لحظه است نه حقیقت
قاعدهای که در تیم خودمان صریح نوشتهایم: پیش از تکیه بر جزئیاتی از یک سند، بررسیاش کنید — و اگر عوض شده بود، سند را در همان تغییر اصلاح کنید.
بند دوم مهمتر است. کسی که متوجه میشود سند غلط است و اصلاحش نمیکند، مشکل را برای نفر بعدی نگه داشته.
قاعدهای که از واگرایی جلوگیری میکند
یک واقعیت، فقط یک خانه.
اگر همان جمله در پنج سند تکرار شود، روزی که عوض شود در یکیشان عوض میشود و چهار تای دیگر غلط میمانند — بدون اینکه کسی بفهمد.
پس هر واقعیتی یک صاحب دارد و بقیه به آن لینک میدهند، نه اینکه تکرارش کنند. جزئیاتش را در یک حقیقت، یک خانه نوشتهایم.
و وقتی چیزی عوض میشود، ادعای قدیمی را در همهٔ مخازن جستوجو کنید. تقریباً همیشه نسخهای هست که یادتان نبود.
چه چیزی کمتر کهنه میشود
بعضی جنسهای مستندات دوام بیشتری دارند — و اگر انتخاب دارید، آنها را بنویسید:
چراییها. دلیل یک تصمیم، با گذشت زمان غلط نمیشود؛ فقط ممکن است دیگر مصداق نداشته باشد. روشش در ثبت تصمیم فنی.
قواعد کسبوکار، که از بیرون میآیند و ریتم تغییرشان کند است.
نقشهٔ کلی سامانه، که بخشها را میگوید نه جزئیاتشان.
و آنچه سریع کهنه میشود: نسخهها، آدرسها، مسیرها، پارامترها. اینها را یا تولید خودکار کنید یا در یک جای متمرکز نگه دارید — نه پخش در متن سندهای مختلف.
آزمون سلامت
سه سؤال که وضعیت واقعی را روشن میکنند:
۱. عضو جدید میتواند با همین مستندات محیط را از صفر بالا بیاورد؟ اگر نه، سند شما ناقص یا کهنه است. این تنها آزمون معتبر است و باید واقعاً یک بار انجام شود، نه فرض.
۲. آخرین بار کِی کسی سندی را بهخاطر غلط بودن اصلاح کرد؟ اگر هیچوقت، یا مستنداتتان بینقص است یا — که محتملتر است — کسی نمیخواندشان.
۳. اگر کلیدیترین نفر فنی فردا نباشد، چه چیزی با او میرود؟ فهرست جواب، فهرست چیزهایی است که باید نوشته شوند.
و یک انتظار واقعبینانه
هیچ تیمی مستندات کاملاً بهروز ندارد و ما هم نداریم. بیشتر خطاهایی که در بازبینیهای داخلی خودمان پیدا کردهایم، از همین جنس بودهاند: ادعایی که روزی درست بوده و کسی دوباره بررسیاش نکرده.
تفاوت در این نیست که این اتفاق نیفتد. در این است که وقتی افتاد، قابل تشخیص و قابل اصلاح باشد — و کسی که سند را میخواند بداند چقدر میتواند به آن تکیه کند.