مستندات فنی یک کار جانبی نیست که پس از کامپایل شدن کد به پایان برسد. مستندات در مرکز هر پروژه نرمافزاری قرار دارد و تعیین میکند که آیا یک توسعهدهنده جدید میتواند در اولین روز خود یک باگ را رفع کند یا اینکه آیا کاربر پس از پنج دقیقه سردرگمی، محصول شما را رها میکند. مستندات خوب به کاربران کمک میکند تا وظایف واقعی خود را انجام دهند. آنها به نگهدارندگان آینده کمک میکنند تا بفهمند چرا یک ماژول وجود دارد و چگونه میتوان بدون از کار انداختن همه چیز، آن را تغییر داد. با این حال، بسیاری از تیمها با مستندات مانند یک کار ثانویه برخورد میکنند؛ مانند یک README که با عجله نوشته شده یا یک صفحه ویکی که رها شده تا از بین برود. نوشتن مستندات واقعاً مفید، مهارتی است که میتوانید آگاهانه آن را بهبود بخشید.
پیش از نوشتن، مخاطبان خود را بشناسید
پیش از اینکه حتی یک عنوان بنویسید، تصمیم بگیرید که چه کسی قرار است آن را بخواند. یک مدیر پایگاه داده که به دنبال تنظیمات connection pool است، هیچ وجه اشتراکی با یک توسعهدهنده فرانتاند که به دنبال props کامپوننت React میگردد، ندارد. کاربران نهایی به مراحل شمارهگذاری شده و اسکرینشات نیاز دارند، نه نمودارهای معماری. آنها میخواهند بدانند چگونه یک PDF خروجی بگیرند، نه اینکه خط لوله رندرینگ (rendering pipeline) چگونه کار میکند. توسعهدهندگانی که در حال ادغام کتابخانه شما هستند، به امضای دقیق توابع (function signatures)، کدهای خطا و قطعهکدهایی که قابل کپی باشند نیاز دارند. مدیران سیستم به پیشنیازهای نصب، متغیرهای محیطی (environment variables) و جریانهای عیبیابی نیاز دارند که با رایجترین حالتهای شکست شروع میشود.
اگر سعی کنید با یک متن طولانی و یکدست به هر سه گروه خدمات ارائه دهید، همه بازنده خواهند بود. مسیرهای جداگانهای ایجاد کنید. حتی یک صفحه واحد میتواند با عناوین شفاف مانند «برای اپراتورها» و «برای توسعهدهندگان کلاینت» به خوبی بخشبندی شود. هدف این است که اصطکاک ذهنیِ پرسیدن این سوال که «آیا این پاراگراف برای من است؟» را از بین ببرید.
حاشیهها را حذف کنید
وضوح بر هوشمندی غلبه میکند. از جملات کوتاه استفاده کنید. از حالت معلوم استفاده کنید. «پایگاه داده را مقداردهی اولیه کنید» شفافتر از «پایگاه داده باید توسط کاربر مقداردهی اولیه شود» است. هرگاه مجبور شدید از یک اصطلاح فنی مانند "idempotency" یا "serialization" استفاده کنید، آن را در همانجا تعریف کنید یا به یک واژهنامه لینک دهید. فرض را بر دانش قبلی مخاطب نگذارید.
یک تست عملی: سعی کنید پاراگراف خود را با صدای بلند بخوانید. اگر نفستان بند آمد، جمله بیش از حد طولانی است. تست دیگر: فعلهای پرطمطراق را با فعلهای ساده جایگزین کنید. اگر عبارتی مانند "utilize the API" میتواند بدون از دست دادن معنا به "use the API" تبدیل شود، این تغییر را انجام دهید. زبان ساده به معنای سادهانگاری نیست؛ بلکه به معنای زبان دقیق و عاری از حاشیهپردازیهای شرکتی است.
ساختاری که واقعاً کمک میکند
یک دفترچه راهنمای بینظم، حتی بیشتر از نبودِ دفترچه راهنما، وقت تلف میکند. مستندات خود را مانند یک قید در نظر بگیرید. در بالا، یک مرور کلی کوتاه قرار دهید که توضیح دهد پروژه چه کاری انجام میدهد و چه کسانی باید به آن اهمیت بدهند. سپس دستورالعملهای نصب را اضافه کنید که هیچ فرضی درباره تنظیمات محلی خواننده نداشته باشد. بعد از آن، آموزشهایی (tutorials) اضافه کنید که سناریوهای کامل و واقعگرایانه را از ابتدا تا انتها طی میکنند. مراجع API در مرحله بعد میآیند. این مراجع باید جامع اما قابل پیمایش (scannable) باشند و به جای ترتیب الفبایی، بر اساس منبع یا تابع گروهبندی شوند. در نهایت، راهنماهای عیبیابی را قرار دهید که به علائم خاص میپردازند. کاربری که با خطای "Connection refused" مواجه میشود، به پاسخی متفاوت از کاربری که "Permission denied" را میبیند، نیاز دارد. خطاها را بر اساس پیام یا زمینه (context) گروهبندی کنید، نه بر اساس دستهبندیهای انتزاعی.
لیستها و بلوکهای کد، متنهای متراکم را از هم جدا میکنند و به خوانندگان اجازه میدهند دستور دقیق مورد نیاز خود را سریع پیدا کنند. یک لیست گلولهای (bullet list) که در جای مناسب قرار گرفته باشد، میتواند یک پاراگراف گیجکننده را به مجموعهای از اقدامات تبدیل کند.
نشان دهید، فقط توضیح ندهید
توضیحات انتزاعی باعث ناامیدی کاربران میشود. اگر نحوه پیکربندی یک ابزار را شرح میدهید، محتویات دقیق فایل را نشان دهید. قطعهکدهای مربوط به نصب، مقداردهی اولیه و پیکربندیهای رایج را ارائه دهید. ورودیهای نمونه و خروجیهای مورد انتظار را در کنار هم نشان دهید. اگر API شما JSON برمیگرداند، همان JSON را نشان دهید. اگر یک ابزار CLI خروجی جدولی تولید میکند، جدول را نشان دهید. هرگز تصور نکنید که شرح یک جریان کاری (workflow) با نمایش عملی آن برابر است.
مهمتر از همه، هر مثال را قبل از انتشار در یک محیط پاک تست کنید. قطعهکد خود را در یک کانتینر یا ماشین مجازی تازه کپی کنید. اگر به دلیل فراموش کردن ذکر یک وابستگی (dependency) با خطا مواجه شدید، با این کار جلوی سیل عظیمی از مشکلات را گرفتهاید. مثالهای ملموس بیشترین بازگشت سرمایه را در نویسندگی فنی دارند، زیرا عدم قطعیت را به عمل تبدیل میکنند.
آن را زنده نگه دارید
مستندات سریعتر از کد فرسوده میشوند. امضای یک متد تغییر میکند، یک پورت پیشفرض جابهجا میشود، یک وابستگی جایگزین میشود و ناگهان دستورالعملهای شما به بنبست ختم میشوند.