مستندسازی در پروژه های نرم افزاری

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

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

کاغذبازی و انجام کارهای متفرقه، می تواند باعث حواس پرتی از کار واقعی شما شود. با این حال، مستندات نرم افزار در مهندسی نرم افزار، بخش اساسی نوشتن یک کد خوب (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)

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

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

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

نوشته ایجاد شد 13

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

نوشته های مرتبط

متنی که میخواهید برای جستجو وارد کرده و دکمه جستجو را فشار دهید. برای لغو دکمه ESC را فشار دهید.

بازگشت به بالا