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

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

چرا به مستندات نیاز داریم؟

• اطلاعات پروژه در ذهن شما نمی‌ماند؛ شش ماه بعد ممکن است بخشی از آن فراموش شود.

• مستندات تغییرات و دلایل آن‌ها را برای تیم و کاربران روشن می‌کند.

• داشتن مستندات نشان می‌دهد که شما برای مشتریان و همکاران ارزش قائلید.

• اگر فقط خودتان کد را بفهمید، احتمالاً تنها خودتان هم می‌توانید از آن استفاده کنید!

انواع مستندات پروژه

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

راهنمای کاربر (User Manual)

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

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

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

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

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

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

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

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

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

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

مستندات تست (QA Documentation)

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

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

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

 

 

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

به صورت کلی در نوشتن مستندات باید نکات زیر رعایت شود :

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

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

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

آموزش (Tutorial)

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

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

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

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

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

توضیحات (Explanations)

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

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

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