Arman Khanegi
Arman Khanegi
خواندن ۴ دقیقه·۴ سال پیش

راه حل نهایی مستندسازی نرم افزار

کنایه "اختراع مجدد چرخ"، به نظر من کنایه خوبیست. هشدار می‌دهد که وقت خود را برای کاری که قبلا انجام شده است تلف نکنید. اما همیشه هم به آن پایبند نیستم، معتقدم که یک کلیشه است و لزوما همیشه درست نیست، حتی در مقابل آن، من توصیه "اختراع مجدد چرخ" را برای خودم دارم.


ما در تیم کاریمان، مشغول کار بر روی مجموعه وسیعی از نرم‌افزارهای مرتبط به هم هستیم. مستندسازی برای کار ما، حیاتیست. به همین دلیل، مدت زمان زیادی در تکاپو برای یافتن و اجرای یک روش مستندسازی، انواع گزینه‌ها را بررسی کردیم. ابزار اصلی ما برای توسعه، ویژوال‌استودیو است و ماژول‌های تحت‌وب و تحت‌ویندوز (و حتی اخیراً ماژول‌های موبایل، در Xamarin) را با این ابزار و تحت فریم‌ورک دات‌نت توسعه می‌دهیم. در ویژوال‌استودیو می‎توانیم قبل از هر کلاس، متد یا متغیری در موردش توضیحات بنویسیم، که معمولا هم می‌نویسیم. نرم‌افزارهایی وجود دارند که این توضیحات را از فایل‌های Xml داخل پروژه جمع‌آوری و در ساختار CHM یا Html تحویل می‌دهند. مثلا GhostDoc. در صورت استفاده از این ابزار، هربار که تغییری در کدها ایجاد می‌کنید باید مستندات مربوطه را بروزرسانی نمایید. از طرفی تمام اطلاعاتی که در نهایت ارائه می‌شود در سطح همان کلاس‌ها و متدهاست.

چیزی که ما لازم داشتیم بالاتر از این‌ها بود. ما می‌خواستیم در مورد معماری سیستم، نحوه تعامل ماژول‌ها با همدیگر، قراردادهای نامگذاری در لایه‌های مختلف، استانداردهای طراحی دیتابیس و خیلی موارد دیگر مستندات داشته باشیم. ضمن اینکه، ابزارهایی که وجود دارند به طور تخصصی بر روی یک موضوع تمرکز دارند، مثلا swagger برای APIها استفاده می‌شود یا برای طراحی شماهای دیتابیس و روابط بین اشیای مختلف دیتابیس، ابزارهای دیگری موجودند، مثلا DBScribe و برای طراحی فرایند و مدلسازی آن نیز ابزارهای دیگری مثلا ابزار مورد علاقه من CPNTools. ما نیاز به ابزاری داشتیم که به صورت مجتمع همه این‌ها را در خود داشته باشد، حتی مواردی که در جاهای دیگر مرسوم نیست، مثلا خلاصه و جمع‌بندی جلساتی که در مراحل تحلیل و مدلسازی یا بررسی نظرات ذینفعان پروژه برگزار می‌شود. حتی روند اداری که منجر به تغییر در فرایندها شده است برای ما مهم است و همینطور ذخیره و ثبت فایلهایی همچون دیاگرام‌ها، چارت‌ها و سایر مستنداتی که در نرم‌افزارهای دیگر تولید می‌شوند.

از آنجایی که اعضای تیم در تمام زمینه‌ها متخصص و صاحب‌نظر نیستند، ضمن استفاده از افراد خبره به عنوان مشاور، مرحله‌ای داریم با نام "مطالعات پیش از اجرا". در این مرحله اعضای درگیر در پروژه (یا مدیر محصول) از تمام منابع در دسترس برای جمع‌آوری اطلاعات در مورد پروژه استفاده می‌کنند. نتایج این مطالعات لازم است به عنوان مستندات ثبت گردد تا در جلسات تحلیل به آن‌ها رجوع شود. و نهایتا امکان تعیین سطح دسترسی برای هر نوع از مستندات در یک پروژه خاص برای افراد خاص و نیز امکان استفاده از مدیاهای صوتی و تصویری از جمله قابلیت‌هایی بودند که نیاز بود در ابزار مورد استفاده وجود داشته باشند.

یکی از رسم‌ها یا استراتژی‌های گوگل که شخصاً خیلی دوست دارم (و البته از غولی همچون گوگل هم انتظار می‌رود که همین‌طور باشد) این است که ابزارهای مورد نیازش را خودش توسعه می‌دهد و می‌سازد. بسیاری از ابزارهایی را که روزمره استفاده می‌کنیم زمانی پروژه‌های داخلی گوگل بوده‌اند که معمولا پس از مدتی عمومی می‌شوند و در اختیار سایر توسعه‌دهندگان هم قرار می‌گیرند. البته و طبیعتا این رویکرد برای تیم‌های کوچک یا حجم کاری محدود مقرون به صرفه نیست اما برای ما راه‌حل نهایی بود.

بله، ما ابزار مستندسازی مورد نیازمان را خودمان توسعه دادیم. هر قابلیتی که نیاز داشته باشیم به آن اضافه می‌کنیم. امکان تعریف ساختارهای درختی دارد و در این ساختارها از همان "مطالعات پیش از اجرا" تا تفکیک پروژه‌های مختلف، قوانین مورد نیاز طراحی در مراحل مختلف، تعریف تک تک Namespaceها، کلاسها، متدها، توضیحات در مورد دیتابیس و اشیای آن و حتی ثبت جلسات کاری قرار می‌گیرند. به صورت تحت وب طراحی شده و در آینده با طراحی افزونه‌هایی برای ویژوال‌استودیو با آن مجتمع خواهد شد. به عنوان یک ابزار کامل است و افزوده شدن یک Task برای ثبت مستندات توسط اعضای پروژه ضمانت اجرایی آن است.

برای ما تا مدت زمان زیادی در وضعیت "در دست توسعه" باقی می‌ماند و تنها، ابزاریست برای اینکه جای خالی امکانات نداشته را پر کند نه جایگزینی برای آنان. ما همچنان در لابلای کدها و در نرم‌افزار طراحی دیتابیس، توضیحات خواهیم نوشت و همزمان به تکمیل و توسعه این ابزار هم خواهیم پرداخت.



پی‌نوشت:

1. محیط و فرایند توسعه خاصی داریم که توضیح آن در حوصله این مطلب نیست.

٢. دوست دارم زماني اين ابزار را در اختيار كساني كه به آن نياز دارند قرار دهم

٣. اگر فكر ميكنيد نيازي به اختراع دوباره نبود با معرفي راهكاري به من اطلاع دهيد

softwaredocumentationنرم افزارمستندسازي
شاید از این پست‌ها خوشتان بیاید