مستندسازی در پروژه های نرم افزاری - براساس اولویت بندی منابع قابل دسترسی

مقاله ای که در ادامه مطالعه می کنید سعی در ارایه انواع روش های مستندسازی پروژه‌ دارد. همچنین کمک می کند دید بهتری به فرایند و دلایل مستند نویسی پیدا کنید.

چرا مستندات برای پروژه می نویسیم؟

کاغذبازی و انجام کارهای متفرقه، می تواند باعث حواس پرتی از کار واقعی شما شود. با این حال، مستندسازی پروژه‌ ها در مهندسی نرم افزار، بخش اساسی نوشتن یک کد خوب (clean code) است.  به عنوان یک برنامه نویس می دانید که باید برخی از انواع مستندات برنامه خود را ارائه دهید. اگر هم مستندی در دسترس نباشد برنامه نویسان دیگر ممکن است از برنامه های شما استفاده نکنند.

انواع مستندات مختلف یک هدف را دنبال می کنند: ” کاربران یک نرم افزار از آن برای انجام کاری مفید در سیستم استفاده کنند.”

در اینجا کلمه کاربران، شامل کسانی که شاغل در آن سیستم هستند نیز می شود. مثلا ارائه مستندات مختلف به کارمندان باعث می‌شود که سریع تر در قالب سیستم قرار گیرند.

ارائه مستندات کاربری مزایای دیگری را نیز داراست:

شما کارهایی که انجام داده اید را در ذهن خود دارید. شش ماه یا یک سال بعد از آن ممکن است برخی از آنها در ذهن شما از بین رفته باشند. مستندات در آینده به شما کمک می کند تا بدون تکیه بر حافظه، از کارهای انجام شده در گذشته استفاده صحیح شود.

داشتن مستندات، روال این تغییرات و دلیل آن را برای استفاده کنندگان مشخص می‌کند.

ارائه انواع صحیح مستندات برنامه جهت نشان دادن اینکه چقدر شما برای مشتریان و کارمندان ارزش قائل هستید، باعث بالا رفتن ارزش برند شما و ارتقا آن می‌شود. (value attribution)

اگر تنها کسی هستید که نرم افزار خود را درک می‌کند، احتمالاً تنها فردی هستید که از آن استفاده می کند یا توسعه می بخشید. این باعث رضایت شماست؟

اگر شخص دیگری باید روی کد شما با بروزرسانی یا تجدید نظر در آن کار کند، مستندات خوب باعث ساده و روان تر شدن روال انجام آن می شود.

انواع مختلف مستندات

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

راهنمای کاربر (User manu als)

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

مستندات کلی پروژه (Project documentation)

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

مستندات نیازمندی‌های پروژه (Requirements documentation)

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

مستندات معماری (Architecture documentation)

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

مستندسازی فنی (Technical documentation)

مستنداتی که برای مخاطبان فنی نوشته شده است، مواردی از قبیل کد، الگوریتم ها و رابطه ها را پوشش می‌دهد.

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

مستندات تست (Quality assurance documentation)

در مبحث مستندات تست نرم افزار عناوین مختلفی وجود دارد:

استراتژی تست

استراتژی تست سندی است که رویکرد تست نرم افزار را برای دستیابی به اهداف تست توصیف می‌کند. این سند شامل اطلاعاتی در مورد ساختار تیم و نیازهایی که باید در طول تست اولویت بند می‌باشد. معمولاً استراتژی تست ثابت است زیرا استراتژی برای کل دامنه توسعه تعریف می‌شود.

برنامه های مدوّن تست

یک روال تست معمولاً از یک یا دو صفحه تشکیل شده است. و باید آنچه را که در یک لحظه معین تست می شود توصیف کند. این سند باید شامل موارد زیر باشد:

لیست ویژگی هایی که باید مورد تست قرار گیرند

• روشهای تست
• چارچوب زمان
• نقش ها و مسئولیت ها (به عنوان مثال تست ممکن است توسط تیم QA یا مهندسین دیگر انجام شود)
• جزییات انواع مختلف تست

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

چک لیست تست های انجام شده

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

راهنمای نگه داری و توصیه های نرم افزاری (Maintenance and help guide)

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

نکاتی در مورد نوشتن مستندات

5 نکته کلی در نوشتن مستندات یک پروژه وجود دارند:

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

مستندات ابتدا نیاز به پیش نویسی دارند.

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

قابلیت استفاده مستندسازی پروژه‌ ها را تست کنید (این باعث تست قسمتی از نرم افزار که می خواهید مستند کنید، توسط خودتان می شود).

این کار به نحوی است که باید مواردی که در مستندات آماده می شود عینا با واقعیات و اتفاق هایی که در سیستم افتاده است برابری کند.

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

مؤلفه های مستندات کاربر

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

آموزش (Tutorial)

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

راهنمایی (A how-to guide)

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

یک راهنمای مرجع (A reference guide)

این راهنما شامل اسناد فنی است که کد و ساختار نرم افزار را پوشش می دهد.

توضیحات (Explanations)

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

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

در پایان به یاد داشته باشید که مستندسازی پروژه‌ و تولید مستندات خوب، به خودی خود، یک محصول است!