مستندسازی نرم‌افزار

مستندسازی نرم‌افزار

مستندسازی نرم‌افزار یا مستندسازی سورس کد (انگلیسی: Software Documentation) متنی مکتوب است که همراه نرم‌افزارها ارائه می‌گردد. این‌گونه متن‌ها معمولاً عملکرد نرم‌افزار و چگونگی استفاده از آن را شرح می‌دهند. این اسناد ممکن است برای افراد مختلف در نقش‌های گوناگون معانی متفاوتی داشته باشد. در مستندسازی، نقش‌ها از اهمیت ویژه‌ای برخوردار هستند.

نقش مستندسازی در توسعهٔ نرم‌افزار

مستندسازی بخش مهمی از مهندسی نرم‌افزار است. مقوله‌های که معمولاً برای مستندسازی مورد توجه قرار گرفته می‌شوند عبارتند از:

1. نیازمندی‌ها –عباراتی که قابلیت‌ها، ویژگی‌ها یا کیفیت‌های یک سیستم را تعریف می‌کنند و زیر ساخت و پایه‌ای برای آنچه که باید اجرا گردد یا اجرا شده است، تلقی می‌گردند. تعریف دقیق و درست نیازمندی‌های نرم‌افزار، افزون برآنکه می‌تواند تفاهمی میان ذی‌نفعان و توسعه‌دهندگان نرم‌افزار باشد، سندی است مشروح از محصولی که در آینده تولید خواهد شد. مستندسازی نیازمندی‌ها تضمین می‌کند که محصول نیازهای ذینفعان را به درستی برآورده خواهد کرد.
2. معماری/طرح – معماری نرم‌افزار و دورنمای آن که نمایش دهندهٔ نحوهٔ تعامل نرم‌افزار با محیط و ساختار و اجزاء نرم‌افزار و روابط میان این اجزاء است.
3. فنی – مستندسازی کد، الگوریتم‌ها، رابط‌های کاربری و رابط برنامه‌نویسی کاربردی.
4. کاربر نهایی – دستور راهنمایی برای کاربران هدف، راهبرهای سیستم و پشتیبان‌های فنی
5. بازاریابی – چگونگی بازاریابی محصول و تحلیل بازار تقاضا

مستندسازی نیازمندی‌ها

مستندسازی نیازمندی‌ها به تشریح و توضیح اینکه یک نرم‌افزار خاص چه می‌کند یا از چه عملکردهایی برخوردار است می‌پردازد. این تشریح در طول توسعه نرم‌افزار مورد استفاده قرار می‌گیرد تا شاخصی باشد برای آنچه نرم‌افزار انجام می‌دهد یا باید انجام بدهد. همچنین این مستندسازی به عنوان یک توافقنامه یا اساسی برای توافقنامه بر آنچه که یک نرم‌افزار انجام می‌دهد یا باید انجام دهد مورد استفاده قرار می‌گیرد. نیازمندی‌ها توسط تمام کسانی که در تولید نرم‌افزار دست‌اندرکار بوده‌اند تولید و مصرف می‌گردد، که تعدادی از آن‌ها عبارتند از: کاربران نهایی، مشتریان، مدیران محصول، مدیران پروژه، فروش، بازاریابی، معماران نرم‌افزار، مهندسین قابلیت مصرف، طراحان تعامل، توسعه‌دهندگان و سنجش‌گران؛ بنابراین، مستندسازی محصول اهداف مختلف و فراوانی را دنبال می‌کند. نیازمندی‌ها به روش‌های گوناگونی ارائه می‌گردد. [نیازمندی]ها می‌توانند به روش: شبه‌هدف (مثلا [محیط کاری توزیع‌شده])، [نزدیک به طراحی] (مثلا، builds می‌توان با راست‌کلیک کردن بر روی یک [فایل تنظیمات|فایل کانفیگیوریشن] و انتخاب گزینه «build» شروع گردد) یا هر روش دیگری ارائه شوند. آن‌ها همچنین می‌توانند به عنوان یک بیانیه به زبان طبیعی، اَشکال، فرمول‌های ریاضی و ترکیبی از همه آن‌ها مشخص گردد. تنوع و پیچیدگی مستندسازی نیازمندی‌ها آن را تبدیل به چالشی حتمی نموده است. ممکن است نیازمندی‌ها تلویحی بوده و به‌سختی پیدا شود. درک این مسئله که هنگام مستندسازی نیازمندی‌ها تا چه اندازه باید پیش برویم و چه میزان را برای تیم‌های مستندسازی دیگر مانند مستندسازان طراحی و مستندسازان معماری واگذار نماییم بسیار دشوار است و دشوارتر از آن، پیاده‌سازی این مستند است بگونه‌ای که گسترهٔ مخاطبان آن که از طراحان و معماران سیستم تا ذینفعان را در بر می‌گیرد را اقناع کند. مستندسازی نیازمندی‌ها معمولاً ناتمام است (یا حتی وجود ندارد). بدون مستندسازی نیازمندی‌ها، تغییرات نرم‌افزاری دشوارتر بوده و به تبع خطای بیشتر (کیفیت نرم‌افزاری کاهش‌یافته) و زمان بیشتری (پرهزینه‌تر) را بر پیاده سازان تحمیل خواهد کرد. اهمیت مستندسازی نیازمندی‌ها رابطه مستقیم با پیچیدگی محصول، تأثیر محصول، و امید به زندگی نرم‌افزار است. اگر نرم‌افزار بسیار پیچیده باشد یا توسط تعداد زیادی از افراد ساخته شده باشد، مستندسازی نیازمندی‌ها کمک می‌کند تا با آنچه که قصد داریم به آن برسیم بهتر ارتباط برقرار کنیم. به عبارت دیگر دورنمای بهتری از محصول نهایی خود داشته باشیم. اگر نرم‌افزار برای امنی تهدید باشد یا تأثیرات منفی برای زندگی بشر داشته باشد (برای مثال، سیستم‌های انرژی هسته‌ای، تجهیزات پزشکی)، مستندسازی نیازمندی‌های رسمی‌تری مورد نیاز خواهد بود. اگر بنابراین باشد که نرم‌افزار تنها یک یا دو ماه عمر کند (برای مثال، اپلیکیشن موبایلی که تنها برای یک کمپین خاص ساخته شده است)، به مستندسازی بسیار کمتری نیاز خواهد بود. اگر قرار است یک نرم‌افزار نسخه اولیه باشد که بعدتر نسخه‌های دیگری بر اساس آن ساخته شوند، مستندسازی نیازمندی‌ها در زمان مدیریت تغییر نرم‌افزار و تأیید اینکه هیچ چیزی در نرم‌افزار در زمان تعدیل شکسته نشده است، مفید خواهد بود. به‌طور سنتی، نیازمندی‌های نرم‌افزار در اسناد نیازمندی‌ها مشخص می‌گردند (برای مثال، کاربرد اپلیکیشن‌های پردازش واژه و اپلیکیشن‌های spreadsheet). برای مدیریت پیچیدگی روزافزون و ذات متغیر مستندسازی نیازمندی‌ها (و به‌طور کلی، مستندسازی نرم‌افزار)، سیستم‌های دیتابیس‌محور و ابزار مدیریت نیازمندی‌ها مبتنی بر اهداف خاص به وجود آمده‌اند که حامیان فراوانی دارند.

مستندسازی معماری/طراحی

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

یک سند معماری مطلوب، کمتر به جزئیات می‌پردازد اما با قدرت توضیح می‌دهد. ممکن است رویکردهایی را برای طراحی سطح‌های پایینتر پیشنهاد دهد، اما جستجوی واقعی مطالعات تجاری را به اسناد دیگر وامی‌گذارد.

نوع دیگری از اسناد طرح سند مقایسه یا سند تجاری است. این سند غالباً شکل یک whitepaper را به خود می‌گیرد. این سند بر بُعد خاصی از سیستم تمرکز می‌کند و روزآمدهای جایگزینی را پیشنهاد می‌دهد و می‌تواند در سطح اینترفیس کاربر، کد، طراحی، یا حتی سطح معماری باشد.
در ضمن دورنمایی از وضعیت موجود ارائه می‌دهد، یک یا چند جایگزین موجود را شرح داده و نقاط ضعف و قوت هر یک را برمی‌شمرد. یک سند مطالعه تجاری خوب در پژوهش سخت‌گیر است، ایده خود را به‌روشنی بیان می‌دارد (بدون تکیه بر سخنان بیهوده که خواننده سردرگم گردد)، و مهم‌تر از همه بی‌طرف است. این سند باید صادقانه و به‌روشنی هزینه تمامی راه‌حل‌هایی را که پیشنهاد می‌دهد به بهترین شکل بیان کند. هدف یک مطالعه تجاری تدوین بهترین راه‌حل است، نه تحمیل یک دیدگاه خاص. ترجیحاً بهتر است که هیچ نتیجه‌گیری‌ای بیان نشود، یا اینکه نتیجه‌گیری گردد که هیچ‌یک از گزینه‌ها بهتر از baseline نیست تا نسبت به تغییر هشداری داده شود. به این سند باید به عنوان تلاشی علمی نگاه کرد، نه یک تکنیک بازاریابی. بخش مهمی از سند طرح در توسعه نرم‌افزار تجاری سند طراحی دیتابیس است (DDD) که شامل المنت‌های طراحی فیزیکی، منطقی و مفهومی می‌گردد.

DDD شامل اطلاعاتی رسمی می‌شود که افرادی که در ارتباط با دیتابیس هستند به آن نیاز دارند. هدف آماده‌سازی آن ایجاد منبعی مشترک برای استفاده تمامی بازیگران صحنه است. کاربران بالقوه از این قرارند:

• طراح پایگاه داده
• توسعه دهندهٔ پایگاه داده
• طراحی برنامه کاربردی
• توسعه دهندهٔ برنامه کاربردی

وقتی که راجع به سیستم‌های دیتابیس رابطه‌ای حرف می‌زنیم، سند باید شامل بخش‌های زیر باشد:

• موجودیت – شماتیک رابطه‌ها (اعم از افزوده یا غیرافزوده)، حاوی اطلاعات زیر به‌همراه تعاریف دقیق آنها:
  • تنظیمات نهاد و خصوصیات آن‌ها
  • روابط و خصوصیات آنها
  • کلیدهای مورد نظر برای هر تنظیم نهاد
  • محدودیت‌های مبتنی بر خصوصیات و Tuple!
• اسکیم رابطه‌ای، که شامل اطلاعات ذیل می‌گردد:
  • جداول، خصوصیات و امکانات آنها
  • ویوها
  • محدودیت‌ها نظیر کلیدهای عمده و کلیدهای بیرونی
  • کاردینال بودن محدودیت‌های مرجع
  • سیساست آبشاری برای محدودیت‌های مرجع
  • کلیدهای اصلی

بسیار مهم است که تمامی اطلاعاتی که قرار است توسط بازیگران این صحنه مورد استفاده قرار گیرد پوشش داده شود. همچنین اهمیت دارد که اسناد را هم هر زمان که تغییری در دیتابیس رخ داد به روز نماییم.

تکنیک Docs-as-Code

"Docs as Code" یک رویکرد نوین برای مستندسازی نرم‌افزار است که مفاهیم و ابزارهای توسعه نرم‌افزار را به فرآیند مستندسازی اعمال می‌کند. در این رویکرد، مستندات همانند کدهای نرم‌افزاری در نظر گرفته می‌شوند و با استفاده از ابزارهای مشابه مدیریت و نسخه‌بندی می‌شوند. اصول کلیدی این رویکرد عبارتند از:

1. استفاده از سیستم‌های کنترل نسخه (VCS): مستندات در سیستم‌هایی مانند Git نگهداری می‌شوند که امکان پیگیری تغییرات، همکاری تیمی و بازگشت به نسخه‌های قبلی را فراهم می‌کند.
2. توسعه مبتنی بر شاخه‌ها (Branch-Based Development): تغییرات مستندات در شاخه‌های جداگانه انجام می‌شود و پس از بررسی و تایید با شاخه اصلی ادغام می‌شوند.
3. ادغام و تحویل مستمر (CI/CD): فرآیندهای خودکار برای بررسی، ساخت و انتشار مستندات استفاده می‌شود. این امر اطمینان می‌دهد که مستندات همواره به‌روز و بدون خطا هستند.
4. بررسی کد (Code Review): تغییرات مستندات قبل از ادغام توسط تیم مورد بررسی قرار می‌گیرد تا کیفیت و دقت آنها تضمین شود.
5. همکاری تیمی: همانند کد، مستندات نیز توسط چندین نفر و با همکاری تیمی توسعه داده می‌شوند.
6. استفاده از ابزارهای خودکارسازی (Automation Tools): برای تولید، ساخت و انتشار مستندات از ابزارهای خودکارسازی مانند Make، Jenkins و سایر ابزارهای مشابه استفاده می‌شود.

مزایا استفاده از تکنیک Docs-as-Code

برای درک چرایی استفاده از تکنیک Docs-as-Code باید به مشکلات سناریوهای قدیمی توسعه مستندات فکر کنیم:

• بواسطه نبود فرهنگ سازمانی Docs-as-Code، مسئول مشخصی (یا تیم مشخصی) برای مستندات پیدا نمی‌شد. حال در رویکرد Docs-as-Code نیاز است که حتما چنین فرد یا تیمی به‌صورت یکپارچه روی مستندات کار کند.
• نبود فضای همکاری در بین تیم‌های مختلف بدلیل استفاده از ابزارهای متفاوت، چالش اصلی سناریوهای قدیمی بود. استفاده از ابزاری مانند Microsoft Office و کُپی کردن محتوا روی وبسایت و تکنیک‌هایی از این دست فضای همکاری را واقعا دشوار کرده و در نتیجه یکپارچگی کُد و مستندات را برهم می‌زند.
• پیگیری تغییرات در نبود فضای یکپارچه، چالش دیگر سناریوهای قدیمی بود. با هر بار تغییر در کدبیس، مستندنویس باید زمانی را برای هماهنگی با برنامه‌نویسان در نظر می‌گرفت و کدها را از آن‌ها دریافت می‌کرد. در نتیجه خودکارسازی کارها کمتر اتفاق می‌افتاد و بیشتر فرایندها به‌صورت دستی پیش می‌رفت.

Docs-as-Code روی یکپارچه‌سازی فضای توسعه و مستندات تمرکز دارد. در نتیجه با ایجاد هماهنگی بین تیم‌های مختلف این امکان را فراهم می‌کند تا روی مستندات تمرکز بیشتری داشته باشیم و تعاملات مستقیم با خود برنامه‌نویسان را برای دریافت تغییرات و اطلاع از چنین مواردی کمتر کنیم. در نتیجه زمان بسیاری صرف نخواهد شد.

جستارهای وابسته

• سندپردازی
• برنامه‌نویسی ادیبانه
• زبان مدل‌سازی یکپارچه

منابع

مشارکت‌کنندگان ویکی‌پدیا. «Software documentation». در دانشنامهٔ ویکی‌پدیای انگلیسی، بازبینی‌شده در ۲۳ ژوئن ۲۰۱۳.

پیوند به بیرون

• kelp - a source code annotation framework for architectural, design and technical documentation.
• automated software documentation بایگانی‌شده در ۲۶ ژوئن ۲۰۱۲ توسط Wayback Machine - application documentation
• ISO documentation standards committee - International Organization for Standardization committee which develops user documentation standards.
• آشنایی با Docs-as-Code - وبلاگ ارسطو عباسی