همان‌قدر که نوشتن کد خوب و اصولی سخت است، نوشتن مستندات خوب که در آینده به کار سایر دولوپرها آید نیز کاری بس دشوار است. در همین راستا، در این مقاله قصد داریم قوانینی که منجر به ایجاد یک Documentation (مستندات) خوب می‌شوند را مورد بررسی قرار دهیم.
برای درک بهتر این موضوع، اجازه دهید دو سناریوی زیر را در مورد دو وب دولوپر مختلف تصور کنیم. در سناریوی نخست، دولوپری به نام تهمینه را می‌بینیم که به تازگی وارد یک پروژهٔ جدید شده و امروز نخستین روز کاری او در این پروژه است. کُدبیس پروژه بسیار خوب و منسجم، تست‌ها عالی و محیط کار فوق‌العاده است. او پشت میز کارش می‌نشیند و بسیار هیجان دارد تا خود را به سرعت به الباقی تیم برساند و هرچه زودتر با همکاران خود سینک (هماهنگ) شود. پس از یک جلسهٔ کوتاه سرپایی با اعضای تیم، تهمینه به سراغ بخشی از مستندات پروژه می‌رود. یکی از همکارانش به نام بیژن -همراه با نگاهی عاقل اَندر سَفیه- برای او توضیح می‌دهد که:
شاید مستندات کمی قدیمی باشه، ولی امیدوارم کارتو راه بندازه.
تهمینه تمام روز را صرف بررسی مستندات می‌کند و در نهایت سردرگم می‌شود که بالاخره بررسی سورس‌کد را از کجا باید شروع کند و اساساً چه‌طور باید از همکارانش راهنمایی بخواهد! بعد از پایان روز کاری، تهمینه همچنان ناامید و سرگردان است و از آن همه شور و شوق دیگر خبری نیست.
در سناریوی دوم دولوپری به نام مهرداد را می‌بینیم که مشغول کار بر روی وب اپلیکیشن خود است. او یک لایبرری پیدا می‌کند که در نگاه اول به طور باورنکردنی مناسب پروژه‌اش به نظر می‌رسد. تلاش می‌کند تا لایبرری را با پروژهٔ خود ادغام کند اما متوجه می‌شود که بعضی از بخش‌های API موجود در این لایبرری بیش از حد مستندسازی شده و برای بعضی بخش‌های دیگر، هیچ‌گونه مستندسازی صورت نگرفته است! مهرداد در نهایت سردرگم می‌شود و این لایبرری را رها می‌کند تا برای پروژهٔ خود به سراغ سولوشِن (راه‌حل) دیگری برود.
در این دو سناریو، شاید کمی بزرگ‌نمایی شده باشد اما به احتمال زیاد بسیاری از ما دولوپرها موقعیت‌های مشابهی را تجربه کرده و به نحوی می‌توانیم با این سناریوها ارتباط برقرار کنیم. این مشکلات به دلیل بی‌کیفیت بودن کد نیست بلکه علت، مستندسازی ضعیف آن است.
چگونه Documentation (مستندات) خوب بنویسیم؟
اگر ارائهٔ مستندات مفید و کاربردی برای موفقیت پروژه‌ها و آسان‌تر کردن کار دولوپرها آن‌قدر مهم است، پس چرا این موضوع در همهٔ پروژه‌ها مورد توجه قرار نمی‌گیرد؟ به نظر می‌رسد مهم‌ترین دلیل‌اش این است که نوشتن مستندات خوب، مانند نوشتن کد خوب، دشوار و زمان‌بر است. به طور کلی، رعایت قوانین زیر می‌تواند به ایجاد مستندات با کیفیت کمک کند که عبارتند از:
مستنداتی بنویسید که گویا و واضح باشند
مهم‌ترین نکته در مورد مستندسازی خوب این است که مستندات تا حد ممکن باید واضح باشند؛ به عبارت دیگر، هدف نهایی باید بیان منظور با استفاده از ساده‌ترین کلمات و جملات باشد به طوری که هیچ مرحله‌ای نیز از قلم نیفتد. ممکن است با خود بگوییم که این موضوع خاص خیلی ساده است و هر کسی دیگر آن را می‌داند؛ اما باید توجه داشت که هر دولوپری پس‌زمینهٔ ذهنی و تجربیات خاص خود را دارد که قطعاً با تجربیات دیگران متفاوت است.
بنابراین همیشه باید فرض کنیم که ممکن است یکی از مخاطبان ما چیزی که به نظر ما بدیهی است را هرگز نداند. با این دیدگاه، ممکن است مستندات ما کمی طولانی‌تر شود اما در عوض بسیار ساده و قابل‌فهم خواهد بود و همهٔ دولوپرها با هر سطحی از تجربه می‌توانند از آن بهره ببرند.
مستنداتی بنویسید که جامع و کامل باشند
نکتهٔ دوم اینکه مستندات باید جامع و کامل باشند؛ به عبارت دیگر، همهٔ جنبه‌های مختلف پروژه را در بر گیرند. فیچرهای مستند نشده و یا اِکسپشن‌ها می‌توانند موجب سردرگمی و اتلاف وقت کسانی شوند که این مستندات را بررسی خواهند کرد زیرا اگر مستندات به آن‌ها کمک نکند، این افراد مجبور خواهند شد تا برای یافتن پاسخ سؤالات خود، به جای مستندات مستقیماً کدها را مورد بررسی قرار دهند. در یک کلام، مستندسازی جامع و همه‌‌جانبه می‌تواند از ایجاد ابهام و سردرگمی جلوگیری کند.
مستنداتی بنویسید که به سرعت بتوان آن‌ها را مرور کرد
سومین نکته این است که مستندات باید طوری نوشته شوند که دیگران بتوانند سریع و راحت مروری کلی بر آن داشته باشند. اگر در مستندات از عناوین مناسب و واضح، فهرست‌های به اصطلاح Bulleted و لینک‌‌های مختلف استفاده شود، خود به خود امکان مرور سریع برای خوانندگان این مستندات فراهم خواهد شد. در پروژه‌های بزرگ، ایجاد فهرست مطالب و یا وجود یک منوی نَویگِیشن (ناوبری) ساده و واضح می‌تواند به کاربران کمک کند تا به جای اسکرول کردن کل مستندات، مستقیماً به سراغ موضوع مورد نظر خود بروند.
مستنداتی بنویسید که مثال‌هایی از نحوهٔ استفاده از نرم‌افزار را بیان کند
نکتهٔ چهارم، مستندسازی مهم‌ترین کاربردهای پروژه است. بدین ترتیب، سایر همکاران می‌دانند که از این کدها چه استفاده‌ای می‌توانند بکنند و اصطلاحاً Use Case سورس‌کد چیست (برای آشنایی بیشتر با این اصطلاح، به لینک Use Case (مورد استفاده) مراجعه نمایید.)
قانون ARID را در مستنداتی که می‌نویسید رعایت کنید
نکتهٔ پنچم مد نظر قرار دادن اصل Accept Repetition In Documentation یا به اختصار ARID است اما پیش از پرداختن به معنا و مفهوم این اصل، نیاز به یک مقدمه داریم. یکی از اصولی که گفته می‌شود باید در کدنویسی رعایت کنیم، اصلی است تحت عنوان DRY که مخفف واژگان Don’t Repeat Yourself است؛ به عبارت دیگر، در حین کدنویسی اصولی باید تا حد ممکن از نوشتن کدهای تکراری پرهیز کرده و این دست کدها را در قالب کلاس‌ها و فانکشن‌هایی درآوریم که به راحتی در هر کجای پروژه که خواستیم مورد استفاده قرار دهیم اما به یاد داشته باشیم که رعایت اصل DRY در حین مستندسازی اصلاً توصیه نمی‌شود!
در پاسخ به این سؤال که چرا در حین نوشتن مستندات نباید قانون DRY را مورد استفاده قرار دهیم، بایستی گفت که خواندن مستندات کاری زمان‌بر و در عین حال خسته‌کننده است و بسیاری از کسانی که مجبور به خواندن چنین محتواهایی هستند، گاهی اوقات سَرسَری اقدام به خواندن نکات فنی می‌کنند، برخی صفحات رو نخوانده رد می‌کنند و در کل آن‌طور که باید و شاید، دل به کار نمی‌دهند.
در همین راستا، رعایت اصل ARID در حین مستندسازی پروژه این تضمین را ایجاد می‌کند تا خوانندگانی از این دست -و حتی خوانندگان بادقت- در جای‌جای مستندات با توضیحات نکات مهم (و در عین حال تکراری) و لینک به بخش‌های قبل و بعد مستندات مواجه شوند تا چنانچه در در بخش‌هایی برخی نکات فنی را از دست داده‌اند، این شانس را داشته باشند تا مجدد آن نکات را مطالعه کنند.
مستنداتی بنویسید که به‌روز باشند
ششمین نکتهٔ مهم، به‌روز نگاه داشتن مستندات است و این موضوع، کار بسیار دشواری است. ممکن است کدنویسی پروژهٔ خود را با ارادهٔ کامل شروع نموده و در آغاز مستندسازی خوبی نیز انجام دهیم؛ اما به محض اینکه درگیر پروژه شدیم و مجبور شدیم که با سرعت زیادی بخش‌های جدید را با کدهای قبلی ادغام کنیم و در عین حال دِدلاین (ضرب‌العجل) پروژه نیز نزدیک است، شاید ترجیح دهیم از مستندسازی صرف‌نظر نماییم و از این روی اگر در یک تیم اجایل کار می‌کنید، توصیهٔ ما این است که یک پروژهٔ مستندسازی نشده را یک پروژهٔ کامل در نظر نگیرید (در پروژه‌های شخصی نیز سعی کنید مستندسازی را به عنوان گام نهایی تکمیل پروژه در نظر داشته باشید.)
مستنداتی بنویسید در صورت نیاز، دیگر دولوپرها بتوانند در تکمیل آن‌ها مشارکت کنند
اگر بخواهیم مستنداتی به اصطلاح Up to Date داشته باشیم، رعایت هفتمین نکته لازم و ضروری است. به عبارت دیگر، باید شرایطی را فراهم کنیم تا سایر دولوپرها در آینده بتوانند در تکمیل، اصلاح و یا حذف بخش‌هایی از مستندات به آسانی وارد عمل شوند.
برای این منظور، همان‌طور که تاریخچهٔ سورس‌کدمان را با استفاده از ورژن کنترل‌هایی همچون Git مدیریت می‌کنیم، مستندات را نیز می‌توانیم با استفاده از ساز و کاری مشابه به صورتی اصولی نسخه‌بندی کرده، مشارکت‌کنندگان در آن را مشخص نموده و در یک کلام، راه را برای سایر دولوپرها هموار سازیم.
مستنداتی بنویسید که جستجوپذیر باشند
به عبارت دیگر، باید بتوانیم به سادگی در مستندات خود سِرچ کنیم و این در حالی است که هر چقدر بتوان مستندات خاصی را آسان‌تر پیدا کرد، مفیدتر واقع خواهند شد. توصیه می‌شود که همواره یک فایل README به‌روز شده داشته باشید و در موارد لزوم، مستندات بیشتر و گسترده‌تر را به آن لینک کنید چرا که این کار می‌تواند یافتن مستندات مورد نظر را آسان‌تر کند.
کلام آخر
امیدواریم این دستورالعمل‌ها بتوانند در نوشتن مستندات‌تان مفید واقع شوند. گاهی اوقات لازم است به یاد بیاوریم که مستندات پروژه را فقط برای سایر دولوپرها نمی‌نویسیم بلکه ممکن است خود ما نیز در آینده به آن نیاز پیدا کنیم و این در حالی است که وقتی پس از چند ماه دوباره به سراغ یک پروژه می‌رویم، به خاطر نوشتن مستندات به‌روز و قابل‌فهم حقیقتاً از خودمان سپاسگزار خواهیم بود.