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

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

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

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

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

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

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

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

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

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

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

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

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

مشارکت‌کنندگان ویکی‌پدیا. «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.