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