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

مستندسازی نرم‌افزار یا مستندسازی سورس کد متنی مکتوب است که همراه نرم‌افزارهای کامپیوتری ارائه می‌گردد. این گونه متن‌ها معمولا عملکرد نرم‌افزار و چگونگی استفاده از آن را شرح می‌دهند که ممکن است برای افراد مختلف در نقش‌های گوناگون معانی متفاوتی داشته باشد.
منظور از مستندسازی نرم‌افزار یا مستندسازی سورس کد، نوشته‌های توصیفی‌ای است که همراه نرم‌افزارهای رایانه‌ای ارائه می‌گردند.
در مستندسازی نقش‌ها از اهمیت ویژه‌ای برخوردارند.
نقش مستندسازی در توسعه نرم‌افزاری
مستندسازی بخش مهمی از مهندسی نرم‌افزاری است. مقوله‌های که معمولا برای مستندسازی مورد توجه قرار گرفته می‌شوند عبارتند از:
نیازمندی‌ها –عباراتی که برای توصیف صفات، قابلیت‌ها، ویژگی‌ها یا کیفیتهای یک سیستم را تعریف می‌کنند زیر ساخت و پایه‌ای برای آنچه که باید اجرا گردد یا اجرا شده است، تلقی می‌گردند. تعریف دقیق و درست نیازمندی، افزون برآنکه می‌تواند مفاهمه‌ای میان ذینفعان و مجریان باشد، سندی است مشروح از محصولی که در آینده تولید خواهد شد و تضمین می‌کند که این محصول نیازهای ذینفعان را به درستی برآورده خواهد کرد.
معماری/طرح – دورنمای نرم‌افزار، که نمایش دهنده نحوه تعامل نرم‌افزار با محیط و ساختار و اجزا نرم‌افزار، به همراه چگونگی روابط میان این اجزا است.
فنی – مستندسازی کد، الگوریتم‌ها، رابط‌های کاربری و APIها.
کاربر نهایی – دستور راهنمایی برای کاربر هدف، راهبرهای سیستم و نیروهای پشتیبان
بازاریابی – چگونگی بازاریابی محصول و آنالیز بازار تقاضا
مستندسازی نیازمندی‌ها
مستندسازی نیازمندی‌ها به تشریح و توضیح اینکه یک نرم‌افزار خاص چه می‌کند یا از چه عملکردهایی برخوردار است می‌پردازد. این تشریح در طول توسعه نرم‌افزار مورد استفاده قرار می‌گیرد تا شاخصی باشد برای آنچه نرم‌افزار انجام می‌دهد یا باید انجام بدهد.
همچنین این مستندسازی به عنوان یک توافقنامه یا اساسی برای توافقنامه بر آنچه که یک نرم‌افزار انجام می‌دهد یا باید انجام دهد مورد استفاده قرار می‌گیرد. نیازمندی‌ها توسط تمام کسانی که در تولید نرم‌افزار دست‌اندرکار بوده‌اند تولید و مصرف می‌گردد، که تعدادی از آن‌ها عبارتند از: کاربران نهایی، مشتریان، مدیران محصول، مدیران پروژه، فروش، بازاریابی، معماران نرم‌افزار، مهندسین قابلیت مصرف، طراحان تعامل، توسعه‌دهدگان و سنجش‌گران؛ بنابراین، مستندسازی محصول اهداف مختلف و فراوانی را دنبال می‌کند.
نیازمندی‌ها به روش‌های گوناگونی ارائه می‌گردد. نیازمندیها می‌توانند به روش: شبه‌هدف (مثلن محیط کاری توزیع‌شده)، نزدیک به طراحی (مثلن، builds می‌توان با راست‌کلیک کردن بر روی یک فایل کانفیگیوریشن و انتخاب گزینه «build» شروع گردد) یا هر روش دیگری ارائه شوند. آن‌ها همچنین می‌توانند به عنوان یک بیانیه به زبان طبیعی، اشکال، فرمول‌های ریاضی و ترکیبی از همه آن‌ها مشخص گردد.
تنوع و پیچیدگی مستندسازی نیازمندی‌ها آن را تبدیل به چالشی حتمی نموده‌است. ممکن است نیازمندی‌ها تلویحی بوده و به‌سختی پیدا شود. درک این مسئله که هنگام مستندسازی نیازمندی‌ها تا چه اندازه باید پیش برویم و چه میزان را برای تیم‌های مستندسازی دیگر مانند مستندسازان طراحی و مستندسازان معماری واگذار نماییم بسیار دشوار است و دشوار‌تر از آن، پیاده‌سازی این مستند است بگونه‌ای که گستره مخاطبان آن که از طراحان و معماران سیستم تا ذینفعان را در بر می‌گیرد را اقناع کند.
مستندسازی نیازمندی‌ها معمولن ناتمام است (یا حتا وجود ندارد). بدون مستندسازی نیازمندی‌ها، تغییرات نرم‌افزاری دشوارتر بوده و به تبع خطای بیشتر (کیفیت نرم‌افزاری کاهش‌یافته) و زمان بیشتری (پرهزینه‌تر) را بر پیاده سازان تحمیل خواهد کرد.
اهمیت مستندسازی نیازمندی‌ها رابطه مستقیم با پیچیدگی محصول، تاثیر محصول، و امید به زندگی نرم‌افزار است. اگر نرم‌افزار بسیار پیچیده باشد یا توسط تعداد زیادی از افراد ساخته شده باشد، مستندسازی نیازمندی‌ها کمک می‌کند تا با آنچه که قصد داریم به آن برسیم بهتر ارتباط برقرار کنیم. به عبارت دیگر دورنمای بهتری از محصول نهایی خود داشته باشیم.
اگر نرم‌افزار برای امنی تهدید باشد یا تاثیرات منفی برای زندگی بشر داشته باشد (مثلن، سیستم‌های انرژی هسته‌ای، تجهیزات پزشکی)، مستندسازی نیازمندی‌های رسمی‌تری مورد نیاز خواهد بود. اگر بنا بر این باشد که نرم‌افزار تنها یک یا دو ماه عمر کند (مثلن، اپلیکیشن موبایلی که تنها برای یک کمپین خاص ساخته شده است)، به مستندسازی بسیار کمتری نیاز خواهد بود. اگر قرار است یک نرم‌افزار نسخه اولیه باشد که بعدتر نسخه‌های دیگری بر اساس آن ساخته شوند، مستندسازی نیازمندی‌ها در زمان مدیریت تغییر نرم‌افزار و تایید اینکه هیچ چیزی در نرم‌افزار در زمان تعدیل شکسته نشده است، مفید خواهد بود.
به‌طور سنتی، نیازمندی‌های نرم‌افزار در اسناد نیازمندی‌ها مشخص می‌گردند (مثلن، کاربرد اپلیکیشن‌های پردازش واژه و اپلیکیشن‌های spreadsheet). برای مدیریت پیچیدگی روزافزون و ذات متغیر مستندسازی نیازمندی‌ها (و به‌طور کلی، مستندسازی نرم‌افزار)، سیستم‌های دیتابیس‌محور و ابزار مدیریت نیازمندی‌ها مبتنی بر اهداف خاص بوجود آمده‌اند که حامیان فراوانی دارند.
مستندسازی معماری/طراحی
مستندسازی معماری (که همچنین به نام توصیف معماری نرم‌افزار نیز شناخته شده است) نوع خاصی از اسناد طراحی به‌شمار می‌رود. به شکلی، اسناد معماری سومین مشتق کد هستند (سند طرح دومین مشتق و اسناد کد نخستین آن‌ها). بخش اندکی در اسناد معماری به خود کد اختصاص داده می‌شود.
این اسناد اشاره‌ای به چگونگی برنامه‌نویسی برای یک روتین بخصوص، و حتی اینکه این روتین خاص چرا به شکلی که الان هست وجود دارد، نمی‌پردازد، لیکن در عوض، طرحی از نیازمندی‌های کلی را که باعث وجود چنین روتینی می‌شوند، می‌ریزد.
یک سند معماری مطلوب، کمتر به جزئیات می‌پردازد اما با قدرت توضیح می‌دهد. ممکن است رویکردهایی را برای طراحی سطح‌های پایینتر پیشنهاد دهد، اما جستجوی واقعی مطالعات تجاری را به اسناد دیگر وامی‌گذارد.
نوع دیگری از اسناد طرح سند مقایسه یا سند تجاری است. این سند غالبا شکل یک whitepaper را به خود می‌گیرد. این سند بر بعد خاصی از سیستم تمرکز می‌کند و روزکردهای جایگزینی را پیشنهاد می‌دهد و می‌تواند در سطح اینترفیس کاربر، کد، طراحی، یا حتی سطح معماری باشد.
در ضمن دورنمایی از وضعیت موجود ارائه می‌دهد، یک یا چند جایگزین موجود را شرح داده و نقاط ضعف و قوت هر یک را برمی‌شمرد. یک سند مطالعه تجاری خوب در پژوهش سخت‌گیر است، ایده خود را به‌روشنی بیان می‌دارد (بدون تکیه بر سخنان بیهوده که خواننده سردرگم گردد)، و مهم‌تر از همه بی‌طرف است. این سند باید صادقانه و به‌روشنی هزینه تمامی راه‌حل‌هایی را که پیشنهاد می‌دهد به بهترین شکل بیان کند.
هدف یک مطالعه تجاری تدوین بهترین راه‌حل است، نه تحمیل یک دیدگاه خاص. ترجیحن بهتر است که هیچ نتیجه‌گیری‌ای بیان نشود، یا اینکه نتیجه‌گیری گردد که هیچ‌یک از گزینه‌ها بهتر از baseline نیست تا نسبت به تغییر هشداری داده شود. به این سند باید به عنوان تلاشی علمی نگاه کرد، نه یک تکنیک بازاریابی.
بخش مهمی از سند طرح در توسعه نرم‌افزار تجاری سند طراحی دیتابیس است (DDD) که شامل المنت‌های طراحی فیزیکی، منطقی و مفهومی می‌گردد.
DDD شامل اطلاعاتی رسمی می‌شود که افرادی که در ارتباط با دیتابیس هستند به آن نیاز دارند. هدف آماده‌سازی آن ایجاد منبعی مشترک برای استفاده تمامی بازیگران صحنه است. کاربران بالقوه از این قرارند:
طراح پایگاه داده
توسعه دهنده پایگاه داده
طراحی برنامه کاربردی
توسعه دهنده برنامه کاربردی
وقتی که راجع‌به سیستم‌های دیتابیس رابطه‌ای حرف می‌زنیم، سند باید شامل بخش‌های زیر باشد:
موجودیت – شماتیک رابطه‌ها (اععم از افزوده یا غیرافزوده)، حاوی اطلاعات زیر به‌همراه تعاریف دقیق آنها:
تنظیمات نهاد و خصوصیات آن‌ها
روابط و خصوصیات آنها
کلیدهای مورد نظر برای هر تنظیم نهاد
محدودیت‌های مبتنی بر خصوصیات و Tuple!
اسکیم رابطه‌ای، که شامل اطلاعات ذیل می‌گردد:
جداول، خصوصیات و امکانات آنها
ویوها
محدودیت‌ها نظیر کلیدهای عمده و کلیدهای بیرونی
کاردینال بودن محدودیت‌های مرجع
سیساست آبشاری برای محدودیت‌های مرجع
کلیدهای اصلی
بسیار مهم است که تمامی اطلاعاتی که قرار است توسط بازیگران این صحنه مورد استفاده قرار گیرد پوشش داده شود. همچنین اهمیت دارد که اسناد را هم هر زمان که تغییری در دیتابیس رخ داد به‌روز نماییم.
سندپردازی
برنامه‌نویسی ادیبانه
زبان مدل‌سازی یکپارچه