با سلام و درود، امروز با بحث زیبای تهیه اسناد تکنیکال (مستندات فنی) در توسعه نرم افزار همراهتون هستم 🙂 مستندات فنی در مهندسی نرم افزار (مستند سازی نرم افزار) اصطلاحی چتر گونه است که شامل تمامی مستندات و مطالب مکتوب مربوط به توسعه محصول نرم افزاری می باشد.تمامی محصولات توسعه نرم افزار، چه توسط تیمی کوچک تولید شده باشند یا یک شرکت بزرگ، نیاز به یک سری اسناد مرتبط دارند و اینکه در طی چرخه زمانی توسعه نرم افزار(software development lifecycle (SDLC)) انواع مختلفی از مستندات ساخته می شود. مستندات وجود دارند تا عملکرد نرم افزار را تشریح کنند، اسناد مرتبط با پروژه را متحد کنند، و امکان بحث روی تمامی سوالات مهم بین صاحبان (ذینفعان) محصول و توسعه دهندگان را بدهد.
ارورهای مستند سازی می تواند منجر به گپ بین دید صاحبان محصول و مهندسین شود و به عنوان نتیجه، راه حل پیشنهادی، انتظارات صاحبان را فراهم نکند. بنابراین، مدیران باید به کیفیت مستند سازی توجه وافری داشته باشند.
رویکرد آبشاری، در رابطه با رویکرد آبشاری قبلا در اینجا به صورت مفصل توضیح داده شده، اینجا دیگه توضیحی در مورد رویکرد آبشاری (Waterfall) نمیدم و اگه اشنایی ندارید همونجا لطف کنید و مطالعه اش کنید. با توجه به PMI’s 9th Global Project Management Survey، رویکرد چابک (Agile) در ۷۱ درصد از سازمان ها برای پروژه هایشان استفاده می شود.
رویکرد چابک، در مورد رویکرد جابک هم قبلا در چندین مطلب به صورت کلی صحبت شده، رویکرد چابک مبتنی بر کار تیمی، همکاری نزدیک بین مشتریان و صاحبان، انعطاف پذیری، و توانایی پاسخ دهی سریع به تغییرات می باشد. بلوک اصلی ساخت و ساز توسعه چابک، تکرار ها هستند، هر کدام از آنها شامل برنامه ریزی، تجزیه و تحلیل، طراحی، توسعه و تست می باشد. توسعه جابک نیاز به مقادیر زیاد مستندات در ابتدای کار نمی باشد. مدیریان نیازی نیست به صورت پیشرفته و زیاد برنامه ریزی کنند، چراکه موارد در تکمیل پروژه هر آن تغییر می کنند. این مورد اجازه برنامه ریزی در لحظه را می دهد.همانطور که یکی از ارزشهای مانیفست چابک بیان می کند : «کار کردن نرم افزار روی مستندات جامع»، ایده این هست که مستندات با اطلاعاتی تولید شود که برای حرکت به جلو ضروری باشند و زمانی که انجام شود ملموس باشند.
امروزه رویکرد چابک بیشترین رویکرد در مهندسی نرم افزار هست، در نتیجه تمرکز ما روی مستند سازی برای این رویکرد می باشد.
انواع مستندات:
هدف اصلی مستندات مؤثر این هست که اطمینان حاصل کند ذینفعان و توسعه دهندگان در جهت یابی اهداف پروژه، هم جهت باشند و در یک جهت هدایت شوند. برای دستیابی به این هدف، تعداد زیادی از انواع مستندات وجود دارد.
طبقه بندی زیر مورد توافق می باشد و با توجه با این طبقه بندی ادامه بحث را پیش می بریم.
تمامی مستندات نرم افزار را می توان به دو دسته بندی اصلی تقسیم کرد:
- مستندات محصول
- مستندات فرآیند
مستندات محصول
محصولی که در حال توسعه است را تشریح می کند و دستورالعمل هایی را برای چگونگی انجام دادن وظایف مختلف با آن فراهم می کند. به طور معمول مستندات محصول شامل الزامات، مشخصات تکنولوژی، منطق بیزینس (Business Logic)، و دفترچه راهنما ها می شود. دو نوع اصلی از انواع مستندات محصول داریم:
- مستندات سیستم اسنادی را ارائه می دهد که خود سیستم و قسمت هایش را تشریح می کنند. این شامل اسناد الزامات، تصمیمات مربوط به طراحی، تشریح معماری، سورس کد برنامه و پرسش و پاسخ های رایج می باشد.
- مستندات کاربر دفترچه های راهنما را پوشش می دهد که برای کاربران نهایی محصول . ادمین های سیستم آماده شده است. مستندات کاربر شامل دستورالعملها، راهنماهای کاربر، کتابچه راهنمای عیب یابی کاربر، کتابچه های راهنمای نصب و مراجع می باشد.
مستندات فرآیند
تمامی اسنادی که در طول توسعه و نگهداری تولید می شوند را شامل می شود که به خوبی فرآیند توسعه را تشریح می کنند. مثال رایج برای اسناد مرتبط با فرآیند استاندارها، اسناد پروژه مانند برنامه ریزی های پروژه، برنامه های زمانی تست، گزارشات، نکات جلسات و یا حتی مکاتبات تجاری می باشد.
تفاوت اصلی بین مستندات فرآیند و محصول این هست که اولی فرایند توسعه را ذخیره می کند و دومی محصولی که در حال توسعه است را تشریح می کند.
محصول: مستندات سیستم
مستندات سیستم یک دیدکلی از سیستم می دهد و به مهندسین و ذینفعان در فهم و درک تکنولوژی های اساسی کمک می کند.
معمولا شامل اسناد الزامات، طراحی معماری، سورس کد، اسناد اعتبارسنجی، اطلاعات تست و تایید، و راهنمای نگهداری می شود. شایان ذکر است که این لیست جامع نیست. در نتیجه، اجازه دهید نگاهی به جزییات انواع اصلی داشته باشیم.
سند الزامات محصول (Product requirement document)
سند الزامات محصول یا (PRD) اطلاعاتی در مورد عملکرد سیستم فراهم می کند. به طور معمول، الزامات عبارت است از آنچه که یک سیستم باید انجام دهد. که شامل قوانین بیزینس (Business Rule)، روایت های کاربر (User Stories)، موارد استفاده (Use Cases) و غیره می شود. این سند باید واضح و روشن باشد و نباید وسیع و دیواری محکم از متن باشد. باید به اندازه کافی برای توصیف محصول دارای ویژگی های آن، عملکردهای آن، نگهداری و رفتار آن باشد.
بهترین کار نوشتن یک سند الزامات با استفاده از یک الگوی منسجم می باشد که تمامی اعضای تیم آن را رعایت کنند. یک فرم وب One-Page به شما کمک خواهد کرد تا سند را مختصر نگه دارید و در صرف زمان برای دسترسی به اطلاعات صرفه جویی کنید. در اینجا به مثالی از سند الزامات یک محصول وب One_page نگاه بیاندازید تا با المان های مختلفی که باید در PRD تان رعایت کنید آشنا شوید. با این وجود باید به خاطر داشته باشید که این تنها راه و نمونه نیست و صرفا برای آموزش و آشنایی شما در اینجا آورده شده است.
اینجا پیشنهادات اصلی که باید در سند الزامات محصول در نظر گرفته شود آورده شده است:
۱- نقش ها و مسئولیت ها (Roles and responsibilities): سند خود را با اطلاعات مربوط به شرکت کنندگان (مشترکین) پروژه شامل صاحب پروژه، اعضای تیم، و ذینفعان آن. این جزییات مسئولیت ها را روشن می کند و اهداف انتشار را برای هر یک از اعضای تیم ارتباط می دهد.
۲- اهداف بیزینس و تجارت (Team goals and business objective): تعریف مهمترین اهداف پروژه در یک فرم کوتاه
۳- پیش زمینه و تناسب استراتژیک (Background and strategic fit): توضیح مختصری از هدف استراتژیک اقدامات خود فراهم کنید. چرا شما محصول را می سازید؟ چطور اقدامات شما روی توسعه محصول تاثیر می گذارد و مطابق با اهداف شرکت است؟
۴- فرضیات (Assumptions): لیستی از فرضیات فنی یا تجاری که تیم احتمالا باید داشته باشد را بسازید.
۵- روایت های کاربر (User Stories): داستانهای کاربر که برای پروژه نیاز است را لیست یا لینک کنید. یک روایت کاربر، سندی است که توسط کاربر از دید خودش که با سیستم نرم افزاری کار می کند نوشته شده است. روایت کاربر توضیح کوتاهی از اقدامات مشتری و نتایجی که میخواهند به آن دست یابند می باشد.
۶- ضوابط پذیرش (Acceptance criteria): شرایطی که نشان میدهد روایت کاربر کامل شده است. هدف اصلی ظوابط پذیرش این است که نتایج لذتبخش برای کاربرد سناریو، از دید کاربر نهایی تعریف کند. بهتره این مقاله را در مورد ضوابط پذیرش برای درک بیشتر این موضوع مطالعه کنید.
۷- طراحی و تعامل کاربر(User interaction and design): اکتشافات مرتبط با طراحی و وایرفریم ها (wireframes) را به صفحه مرتبط کنید.
۸- سوالات (Questions): به عنوان تیمی که مشکلات را در طول پیشرفت پروژه حل می کنند، آنها به ناچار سوالات زیادی خواهند داشت. یک تمرین خوب این است که تمامی این سوالات را ضبط کرده و آنها را ردیابی کنید.
۹- انجام ندهید (Not doing): مواردی که الان در حال انجام شان نیستید را لیست کنید ولی به زودی برای انجامشان برنامه ریزی کنید. چنین لیستی به شما در سازماندهی کارگروهی و اولویت بندی ویژگی ها کمک می کند.
با استفاده از روش های زیر، تمامی این اطلاعات را جامع کنید:
- از لینک ها و anchors (لنگرها) استفاده کنید، آنها به شما کمک می کنند که اسناد را راحت تر بخوانید و جستجو کنید (چرا که خوانندگان می توانند به تدریج اطلاعات را درک کنند) به عنوان نمونه، شما می توانید لینک هایی را به مصاحبه های با مشتری فراهم کنید و به بحث های قبلی یا دیگر اطلاعات اضافی مرتبط با پروژه قلاب کنید.
- از ابزار دیاگرام استفاده کنید تا مسئله ها را بهتر با تیم تان ارتباط دهید. افراد یک سند تصویری را خیلی بهتر از یک سند متنی گسترده درک می کنند. مدلهای تصویری مختلف به شما کمک می کند تا این وظیفه را انجام دهید و الزامات را موثرتر مطرح کنید. شما می توانید با استفاده از ابزارهای زیر دیاگرام ها را در فرآیند الزامات استفاده نمایید : Visio, Gliffy, Balsamiq, Axure یا SmartArt درMicrosoft Office.
مستند سازی طراحی تجربه کاربری (User Experience Design documentation)
طراحی تجربه کاربری از مرحله الزامات شروع می شود و در طول تمامی مرحله های توسعه از جمله تست کردن، و مراحل بعد از انتشار نیز ادامه دارد. فرآیند طراحی UX شامل تحقیق، نمونه سازی (prototyping)، تست استفاده پذیر بودن، و قسمت طراحی حقیقی می باشد که طی آن مستندات و تحویل های زیادی تولید می شود.
مستندات UX را می توان به مراحلی تقسیم کرد. مرحله تحقیق شامل موارد زیر می شود:
- User personas
- User scenario
- Scenario map
- User story map
- UX style guide
شخصیت های کاربر (user personas)، در طول مرحله تحقیق، ساخته شده و مستند می شوند. اطلاعات در طول مصاحبه کاربر جمع آوری شده و بررسی و ممیزی آن در اسناد شخصیتی عملکردی کاربر گردآوری می شود. user personas کاراکتری های اصلی کابران واقعی را با تمرکز بر رفتار، الگوهای فکری و انگیزه شان نشان می دهد.
سناریوی کابر (user scenario) سندی است که قدم هایی که یک user persona برخواهد داشت تا یک وظیفه خاص را انجام دهد، مشخص می کند. سناریوی کاربربه جای آنکه فرآیند تفکر کاربررا تشریح کند تمرکز بر این دارد که یک کاربر چه خواهد کرد. مجموعه سناریو ها می توانند بصری یا روایی باشند، و سناریوهای موجود یا عملکردهای آینده را توصیف کنند.
نقشه های سناریو(Scenario maps )، استفاده می شوند تا سناریوهای کاربر موجود را در یک سند گردآوری کند. نقشه سناریو تمامی سناریوهای امکان پذیر که در زمان داده شده دردسترس هستند را نشان می دهد. هدف اصلی از نقشه سناریو نمایش دادن تمامی سناریوهای ممکن برای هر تابع تنها (single function) و همچنین قدمهای متقاطع سناریو می باشد.
نقشه روایت کاربر (user story map) از روی کارناتمام محصول ساخته می شود. این نوع از سند به مرتب کردن روایت های کاربر به توابع یا قسمت های بعدی از اپلیکیشن کمک می کند. نقشه روایت مشتری می تواند یک شِما/طرح باشد، یا یک جدول از روایت های کاربر که به تریتب خاصی جهت نشان دادن توابع مورد نیاز گروه بندی شده اند، باشد.
راهنمای استایل UX (UX style guide)سند ی است که شامل الگوهای طراحی برای محصول آینده می شود. همچنین تمامی المان های ممکن UI و انواع محتوای استفاده شده را تشریح می کندو قوانینی برای آنکه چگونه آنها باید مرتب شوند و با یکدیگر کار کنند را تعریف می کند. اما بر خلاف UI style guide، طراحان UX ظاهر حقیقی واسط را توصیف نمی کنند.
در مرحله نمونه سازی (prototyping) و طراحی (designing) یک طراح UX اغلب با مستندات تحویل پذیر و بروزشده به طور مساوی بین دیگر اعضای تیم، مانند صاحب محصول، طراحان UI و تیم توسعه کار می کند. مهمترین اسناد تولید شده دراین مرحله عبارت هستند از :
- Site maps
- Wireframes
- Mock-ups
- Prototypes
- User flow schemes or user journey
- Usability testing reports
نقشه سایت/محصول (site/product map) طرحی بصری است که ارتباطات بین تمامی صفحات یک محصول را نشان می دهد. این نقشه به کل تیم کمک می کند تا ساختار یک وبسایت یا اپلیکیشن و ارتباطات بین توابع/صفحات را تجسم کنند. ایجاد نقشه سایت بخشی از چیدن معماری اطلاعات است.
جریان کاربر یا رویه های سفر کاربر (User flow or user journey schemes) به تیم کمک می کند تا گام هایی که یک کاربر ممکن است در تمامی محصول طی کند را ترسیم کند. وظیفه اصلی در رویه ی جریان کاربر (user flow scheme)، این است که گام های ممکن که یک کاربر ممکن است از یک صفحه به صفحه دیگر بردارد را تشریح کند. معمولا رویه شامل تمامی صفحات، بخش ها، دکمه ها و توابعی که برای نمایش منطق حرکت کاربر در نظر گرفته اند، می باشد.
وایر فریم (Wireframes )، طرح هایی برای UI آینده هستند. اصولا، وایرفریم ها طرح هایی هستند که نشان می دهند چگونه المان ها را در صفحه مرتب کنیم و المان ها چگونه باید رفتار کنند. اما وایرفریم ها نشان نمی دهند که شکل المان ها چگونه باید باشد.
mock-up مرحله بعدی طراحی محصول می باشد که ظاهر واقعی و حس یک محصول را نشان می دهد. اصولا mock-up تصاویر ایستایی هستدند که طراحی نهایی نرم افزار را نشان می دهند.
یک نمونه (Prototype) یک mock-up هست که می توانید با آن تعامل داشته باشید: بعضی از دکمه ها را کلیک کنید، بین صفحات مختلف حرکت کنید و غیره. یک پروتوتایپ می تواند در یک ابزار پروتوتایپ همچون Sketch یا MockFlow طراحی شود. با استفاده از قالب ها، طراحان UX می توانند mock-up های تعاملی را در مراحل ابتدایی توسعه بسازند تا برای تست قابلیت استفاده، به کار گرفته شوند.
گزارش تست قابلیت استفاده (usability testing report)، فرم کوچکی از سند بازخورد می باشد که برای برقراری ارتباط نتایج تست قابلیت استفاده، ساخته می شود. گزارش باید تا جای ممکن کوتاه باشد و مثال های بصری بر متن حاکم باشند.
سند معماری نرم افزار
اسناد طراحی معماری نرم افزار شامل تصمیمات اساسی معماری می شوند که توسط معمار حل مسئله (solution architect) گرفته می شوند. ما توصیه نمی کنیم که همه چیز را لیست کنید، اما روی مناسب ترین و چالش برانگیزترین آنها تمرکز کنید. یک سند طراحی و معماری موثر، بخش های اطلاعاتی زیر را شامل می شود:
قالب سند طراحی نرم افزار (Software design document template). گفتگو و ایجاد اجماع با ذینفعان در مورد آنچه که در سند طراحی معماری باید قبل از آنکه ساخته شود در نظر گرفته شود و استفاده از یک قالب تعریف شده برای ترسیم راه حل های معماری.
اصول معماری و طراحی (Architecture & Design Principles). تائید کردن معماری راهنما و اصول طراحی که شما با ان محصول را مهندسی خواهید کرد. برای نمونه، اگر برنامه دارید که راه حل تان را با استفاده از معماری میکروسرویس ساختار دهید، فراموش نکنید که این موضوع را به طور خاص اشاره کنید.
تشریح روایت کاربر (User Story description). ارتباط دادن روایت های کاربر با فرآیندهای تجاری مرتبط و سناریو های مرتبط. شما باید از جزییات فنی در این بخش اجتناب کنید.
جزییات راه حل (Solution details). راه حل در نظر گرفته شده را با استفاده از سرویس های برنامه ریزی شده، ماژول ها، کامپوننت ها و اهمیت آنها تشریح کنید.
نمایش راه حل به صورت نموداری (Diagrammatic representation of the solution). نمودارهایی که برای کمک به درک و ارتباط ساختار و اصول طراحی باید ساخته شوند را مشخص کنید.
در زیر دیاگرام معماری وب اپلیکیشن Azure را مشاهده می کنید:
سند سورس کد (Source code document)
یک سند سورس کد بخشی فنی است که تشریح می کند کدها چگونه کار می کنند. درحالی که ضروری نیست جنبه هایی که بیشترین پتانسیل سردرگمکی را دارند، پوشانده شوند. کاربران اصلی اسناد سورس کد مهندسین نرم افزار هستند.
اسناد سورس کد ممکن است شامل موارد زیر باشند (توجه داشته باشید محدود به این موارد نمی شود):
- چارچوب تولید HTML و دیگر فریمورک های استفاده شده
- نوع اتصال داده ها (data binding)
- الگوهای طراحی با مثال (model-view-controller)
- معیارهای امنیت
- دیگر الگوها و اصول
تلاش کنید که سند را با ساخت بخش های کوچک برای هر المان و پشتیبانی از آنها با توصیفات مختصر، ساده نگهدارید.
مستند سازی تظمین کیفیت
انواع مختلفی از اسناد تست در رویکرد چابک وجود دارد. ما به رایج ترین آنها پرداخته ایم:
- نقشه مدیریت کیفیت (Quality management plan)
- استراتژی تست (Test strategy)
- نقشه تست (Test plan)
- مشخصات Test Case ها
- چک لیست تست
برنامه مدیریت کیفیت (quality management plan) یک آنالوگ از سند نیازمندی ها مختص تست کردن می باشد. این سند، مجموعه استانداردهای مورد نیاز برای کیفیت محصول و روش های رسیدن به این سطح را تشریح می کند. نقشه کمک می کند تا وظایف QA برنامه ریزی شود و فعالیت های تست کردن برای مدیریان محصول را مدیریت می کند، اما اساسا برای پروژه های در مقیاس بزرگ استفاده می شود.
استراتژی تست (test strategy)، سندی است که رویکرد تست کردن نرم افزار را جهت دستیابی به اهداف تست تشریح می کند. این سند شامل اطلاعاتی در رابطه با ساختار تیم و منابع مورد نیاز به همراه اولویت بندی که باید در طول انجام تست شوند، می باشد. یک استراتژی تست معمولا ایستا (Static) است زیرا برای کل دامنه توسعه تفریف می شود.
نقشه تست (test plan)، معمولا از یک یا دو صفحه تشکیل شده و تشریح می کند که چه چیزی باید در لحظه داده شده تست شود. این سند باید شامل موارد زیر باشد:
- لیست ویژگی هایی که باید تست شود
- روش های تست
- چارچوب زمانی Timeframes
- نقش ها و مسئولیت هایشان (برای مثال unit tests ممکن است با تیم QA انجام شود یا توسط مهندسین)
سند مشخصات test case (test case specifications) مجموعه ای از عملیات جزیی می باشد که هر ویژگی یا عملکرد یک محصول را تایید می کند. معمولا یک تیم QA برای هر واحد از محصول، سند مشخصات جداگانه ای می نویسد. مشخصات test case مبتنی بر رویکردی که قبلا در نقشه تست تایید شده می باشد. یک عمل خوب این است که توضیحات مشخصات را ساده سازی کنیم و از تکرار test case ها پرهیز شود.
چک لیست تست (Test checklist) لیستی از تست ها می باشد که باید در زمان مشخصی اجرا شوند. نشان می دهد که چه تست هایی کامل شده اندو چه تعداد شکست خورده اند. تمام نکات در چک لیست های تست باید به درستی تعریف شوند. سعی کنید نکات تست ها را در چک لیست ها گروه بندی کنید. این رویکرد به شما کمک می کند که آنها را در طول کارتان پیگیری کنید و هیچ کدام را از دست ندهید. اگر این به تست کننده ها در بررسی اپلیکیشن به طور صحیح کمک کند، شما می توانید نظارت خود را به نکات مورد نظر در لیست وارد کنید.
نگهداری و راهنما (Maintenance and help guide) این سند باید مسائل شناخته شده و راه حل هایشان را تشریح کند. همچنین باید وابستگی های بین بخش های مختلف سیستم را نشان دهد.
مستند سازی API، تقریبا هر محصولی APIهای خودش را دارد (رابط های برنامه نویسی اپلیکیشن – Application Programming Interfaces). مستندات آنها، به برنامه نویسان اطلاع می دهد که چگونه به طور موثر از API مورد نیازاستفاده کرده یا به آن متصل شوند.
مستندات API یک سند قابل تحویل است که توسط نویسندگان فنی به عنوان آموزش و راهنمای استفاده، تهیه می شود. این نوع از مستند سازی باید دارای لیستی از تمام API های موجود به همراه ویژگی ها ی مختص به هر کدام شان باشد.
محصول : مستندات کاربر
همان طور که از نام پیشنهادی پیداست، مستندات کاربر برای کاربران محصول تهیه می شوند. با این حال، دسته بندی آنها ممکن است متفاوت باشد. پس شما باید مستندات کاربر را با توجه به وظایف متفاوت کاربران و سطح متفاوت تجربه شان، ساختار دهی کنید. معمولا مستندات کاربر در دو دسته بزرگ هدف قرار می گیرد:
- کاربران نهایی
- ادمین های سیستم
مستندات ساخته شده برای کاربران-نهایی (end-users) باید در کوتاهترین روش ممکن که نرم افزار می تواند به حل مسئله هایشان کمک کند، توضیح داده شوند. بعضی از قسمت های مستندات کاربر، همچون دستورالعمل ها و onboarding (معارفه و معاشرت سازمانی – عمل یا فرآیندی که برای هماهنگ سازی و یکپارچگی کارمند جدید درون سازمان رخ می دهد یا آشنا کردن مشتری جدید با یکی از محصولات و یا خدمات را Onboarding می نامند ) در بسیاری از محصولات بزرگ مبتنی بر مشتری با آموزشهای onboarding جایگزین شده است. یا این وجود، هنوز سیستم های پیچیده ای وجود دارند که نیاز به راهنما های مستند کاربر دارند.
شکل آنلاین مستندات کاربر نیازمند این است که نویسندگان فنی دارای قوه ی تصور بیشتری باشند. مستندات آنلاین کاربر-نهایی باید شامل بخش های زیر باشد:
- سوالات متداول (FAQ)
- آموزشهای تصویری
- دستیار جاسازی شده (Embedded assistance)
- پرتال های پشتیبانی
برای ارائه بهترین خدمات برای کاربران-نهایی، شما باید بازخوردهای مشتریان تان را بطور مداوم جمع کنید. سیستم ویکی، یکی از روش های مفید می باشد. ویکی کمک می کند که مستندات فعلی نگهداری شود. اگر شما از سیستم ویکی استفاده کنید نیازی ندارید تا اسناد را به فرمت قابل ارائه در آورید و آنها را روی سرور آپلود کنید. شما می توانید صفحات ویکی خود را با استفاده از wiki markup language و کدهای HTML بسازید.
اسناد ادمین های سیستم (System administrators) نیازی به این ندارد که اطلاعاتی در مورد چگونگی کار با سیستم برای شان فراهم شود.معمولا، اسناد ادمین نصب و بروزرسانی را شامل می شود که به ادمین سیستم در نگهداری از سامانه کمک می کند. در ادامه اسناد استاندارد ادمین های سیستم را مشاهده می کنید:
- توضیحات عملکردی (Functional description) – عملکردهای محصول را تشریح می کند. اکثر قسمت های این سند بعد از مشورت با یک کاربر یا یک صاحب محصول تولید می شود.
- راهنمای ادمین سیستم (System admin guide) – توضیح رفتارهای متفاوت از سیستم در محیط های متفاوت و با دیگر سیستم ها را تشریح می کند. همچنین دستورالعمل هایی را برای نحوه مقابله با شرایط نقص سیستم ارائه می کند.
مستندات فرآیند
مستندات فرآیند تمامی فعالیت ها حول توسعه محصول را در بر می گیرد. ارزش نگهداری مستندات فرآیند این هست که توسعه را سازماندهی شده تر حفظ می کند و به خوبی برنامه ریزی می کند. این شاخه از مستندات نیاز به مقداری برنامه ریزی کار دستی هم قبل ازشروع پروژه وهم در طول توسعه دارد. اینجا انواع متداول مستندات فرآیند را ملاحظه می کنید:
نقشه ها، تخمین و برنامه های زمانی(Plans, estimates, and schedules). این اسناد معمولا قبل از شروع پروژه ایجاد می شوند و به هنگام تکمیل پروژه می توانند اصلاح شوند.
گزارشات و معیارها (Reports and metrics)، گزارشات چگونگی استفاده از منابع انسانی و زمانی که در طول توسعه استفاده شده اند را منعکس می کند. آنها می توانند روزانه، هفتگی یا ماهانه تولید شوند. برای آشنایی بیشتر با مستندات فرآیند اینجا را نگاهی بیاندازید (مواردی مانند چت های سرعتی، نمودارهای burndown و sprint burndown ).
مقالات طرز کار (Working Papers)، این اسناد وجود داردند تا ایده هاو افکار مهندسین که در طول پیاده سازی پروژه وجود دارند را ثبت کنند.مقالات طرزکار معمولا شامل اطلاعاتی در مورد کد مهندسین، طراحی ها (sketches) و ایده ها برای چگونگی حل مسائل فنی می باشد. گرچه آنها نباید منبع اصلی اطلاعات باشند، اما پیگیری آنها بازیابی جزییات بسیار خاصی از پروژه را در صورت نیاز، امکان پذیر می کند.
استانداردها، بخش استانداردها باید تمام کد ها و استاندارد های UX که تیم در طی پیشرفت پروژه به آنها پایبند است را شامل شود.
بیشتر اسناد فرآیند مختص یک زمان یا مرحله خاصی از فرآیند هستند. در نتیجه، این اسناد به سرعت منسوخ و تاریخ گذشته می شوند. مام همچنان باید به عنوان بخشی از توسعه حفظ و نگهداری شوند، چرا که ممکن است برای پیاده سازی وظیفه ای مشابه یا نگهداری در آینده مناسب باشند. همچنین مستندات فرآیند کمک می کنند تمامی توسعه شفاف تر و مدیریت شان ساده تر باشد.
هدف اصلی مستندات فرآیند کاهش مقدار مستندات سیستم می باشد. برای رسیدن به این هدف نوشتن مستندات را به صورت حداقل برنامه ریزی کنید. به هنگام لیست کردن، مخاطبین اصلی، تاریخ های انتشار و انتظارات را همراه با فرضیات در نظر بگیرید.
نقشه راه محصول چابک (Agile product roadmaps)
نقشه راه های مصحول در توسعه نرم افزار چابک به جهت مستند کردن چشم انداز(Vision)، استراتژی و اهداف کلی پروژه استفاده می شوند. نقشه های راه به عنوان اسناد فرآیند استفاده می شوند تا روند توسعه را بجهت همگام سازی با اهداف پایه حفظ کنند. با توجه به نوع نقشه راه محصول، می تواند اهداف سطح-بالا، اولویت بندی وظایف، جدول زمانی اسپرینت یا جزییات سطح-پایین را بیان کند.
سه نوع از نقشه راه محصول وجود دارد که توسط تیم های محصول چابک استفاده می شوند:
- نقشه راه استراتژی (Strategic roadmap)
- نقشه راه تکنولوژی یا آی تی (Technology or IT roadmap)
- نقشه انتشار (Release plan)
نقشه راه استراتژی (strategic roadmap)، یک سند استراتژی سطح بالا می باشد که شامل اطلاعات کلی روی پروژه می باشد. نقشه راه های استراتژیک معمولا یک چشم انداز و اهداف بلندـمدت را بیان می کند. در مورد توسعه محصول چابک، نقشه راه می تواند در مضامینی مرتب شود. مضامین وظایف چندگانه ای هستند که یک تیم باید آنها را کامل انجام دهد و به نوعی با آن در ارتباط باشد. برای نمونه، یک مضمون می تواند مانند «افزایش سرعت بارگذاری صفحه » باشد که مستلزم چندین اقدام می باشد.
گروه بندی اطلاعات در حول مضامین، یک نقشه راه را بسیار منعطف و قابل بروزرسانی می کند، که برای توسعه مبتنی بر اسپرینت (sprint-based development) خیلی مناسب می باشد. بهترین توضیح در مورد نقشه راه استراتژی این است که تنها شامل اطلاعات مهم باشد. در غیر این صورت شما نقشه راه خود را به یک طرح/نقشه دست و پاچلفتی تبدیل می کنید، که هم فهم و هم نگهداری آن سخت است.
نقشه راه تکنولوژی یا نقشه راه آی تی سند سطح پایینی می باشد که نیامندی های فنی و ابزار پیاده سازی فنی را تشریح می کند. نقشه راه های IT کاملا جزیی می باشند. آنها شامل اطلاعاتی مربوط به هر تحویلی هستند و دلیل چنین تصمیمی را تشریح می کنند.
نقشه انتشار (Release Plan)، استفاده می شود تا محدودیت های زمانی برای انتشار را تنظیم کند. یک نقشه انتظار باید بدون مشخص کردن جزییات انتشار، تمرکز بر ضرب الاجل های (deadlines) واقعی داشته باشد.
خیلی توصیه می شود که برای ساخت نقشه های راه خودتان، از ابزارهای مختص نقشه راه استفاده کنید. ابزارهای آنلاین همچون Roadmunk قالی های مختلفی را برای نقشه راه محصول فراهم کرده است، اجازه ویریاش سریع را می دهد و همچنین اشتراک گذاری ساده بین تمامی اعصای تیم را فراهم کرده است.
به خاطر داشته باشید که یک نقشه راه، وابسته به نوع آن، می تواند یک سند محصول باشد که نیازمندی های آن را بیان می کند. همچنین فرآیند را تشریح کرده و تیم شما را در طول توسعه راهنمایی می کند.
ابزار برای مستند سازی نرم افزار
ابزارهای عمومی برای مستند سازی نرم افزار
ابزارهای مشترک بیشماری برای تیم های توسعه نرم افزار وجود دارد که می توانند در بیان نیازمندی ها، اطلاعات اشتراکی و سند کردن ویژگی ها و فرآیندها کمک کنند:
- Atlassian Confluence رایج ترین ابزار پروژه تعاملی می باشد که اکو سیستم کاملی برای مدیریت نیازمندی های محصول و نوشتن مستندات دارد. confluence برای سیستم ویکی پایدارش و واسط موثر مدیریت روایت کاربرش شناخته شده است.
- Github نیازی به معرفی نداره، جز برای افرادی که میخواهند از آن برای مستند کردن نرم افزار استفاده کنند. گیت هاب برای شما سیستم ویکی خودش را فراهم می کند و اجزاه می دهد مستندات خود را به یک وب-سایت الزام آور تبدیل کنید.
ویرایشگرهای Markdown
از آنجایی که استفاده از اسناد با استفاده از محیط وب ساده تر می باشد، در منتیجه باید در فرمت مناسب تهیه شود. یه همین دلیل هست که text-based markup languages ها استفاده می شوند. معروفترین شان Markupهست که به سادگی می تواند به HTML تبدیل شود، بدون نیاز به اطلاعات خاصی برای استفاده از آن.Markup روی گیت هاب و رددیت Reddit و اساسا هرجایی که برای مستند سازی تحت وب هست، استفاده می شود. بنابریان یه تعداد ویرایشگر Markup که می توانند برای تهیه سند برای پروژه شما مناسب باشند را در پایین معرفی کرده ایم:
ابزارهای تخصصی نقشه راه
تمرین خوبی هست که از ابزارهای تخصصی نقشه راه استفاده کنید به این خاطر که آنها به شما اجازه می دهند که اطلاعات را به سرعت به اشتراک بگذارید، تایم لاین ها یا مضامین را بروزرسانی کنید، موضوعات جدیدی اضافه کنید و کل ساختار را ویرایش کنید.اکثر ابزارهای نقشه راه قالب هایی را برای نقشه راه های متفاوت فراهم کرده اند تا به شما اجازه شروع کارکردن کار به صورت فوری را بدهند.
ابزار موجود برای مستند سازی UX
رایج ترین ابزارها برای طراحی تجربه کاربری ابزار های prototyping هستند که کمک به ساخت sketcheها، mock-upها،wireframeها و پروتوتایپ های تعاملی می کند.
ابزار برای مستند سازی API
فرآیند ایجاد کردن مستندات API اغلب به صورت خودکار می باشد. برنامه نویسان یا نویسندگان فنی ممکن است اسناد را بهص ورت دستی بنویسند یا از تولید کننده های اسناد APIاستفاده کنند.
- Swagger یک سرویس نرم ازفزاری رایگان خود-سندساز است که برای ایجاد و بروزرسانی وب سرویس های RESTful و API ها استفاده می شود.
- RAML 2 HTML یک سندساز ساده است که از ویژگی های RAMLاستفاده می کند.
نمونه و قالب برای مستند سازی نرم افزار
اگر تیم تان درتلاش برای پیدا کردن یک الگوی کیفی جهت برخی از انواع مستندات نرم افزار است، در ادامه منابعی برای قالب های مستند سازی است:
چگونه مستندات نرم افزار را بنویسیم: توصیه عمومی
چندین تمرین عام وجود دارد که باید برای تمامی انواع اصلی مستندات که در موردشان بالا بحث کردیم اعمال شود :
فقط به اندازه کافی مستند کنید
شما باید تعادلی بین بدون سند سازی و سندسازی بیش از حد ایجاد کنید. سند سازی ضعیف منجر به خطاهای زیادی می شود و کارایی را در هر فاز از توسعه محصول نرم افزاری کاهش می دهد. در عین حال، نیازی نیست که به وفور سند تهیه کنید و اطلاعات را در صفحات متفاوت تکرار کنید. فقط ضروری ترین و لازم ترین اطلاعات را مستند کنید. یافتن تعادل صحیح همچنین مستلزم تجزیه و تحلیل پیچیدگی پروژه قبل از شروع توسعه می باشد.
مستند سازی فرآیندی مداوم است
به این معنی که شما باید مستندات خود را بروز نگه دارید. خیلی مهمه اسنادی که جاری نیستند، به صورت خودکار ارزش خود را از دست می دهند. اگر الزامات در طول توسعه نرم افزار تغییر کنند، شما نیاز دارید که مطمین شوید فرآیند سیستمی بروزرسانی اسنادی وجود دارد که اطلاعات تغییر یافته را در نظر می گیرد. شما می توانید از کنترل ورژن خودکار برای مدیریت موثرتر این فرآیند استفاده کنید.
مستند سازی تلاشی تعاملی (collaborative) برای تمام اعضای تیم می باشد
روش چابک مبتنی بر رویکرد collaborative برای ایجاد مستندات می باشد. اگر می خواهید به کارایی دست پیدا کنید، برنامه نویسان و تستر ها را در مورد عملکردهای نرم افزار مصاحبه کنید. سپس، بعد از نوشتن مقدار از مستندات، آن را با تیم خود به اشتراک بگذارید و بازخورد بگیرید. جهت گرفتن اطلاعات بیشتر تلاش کنید نظر بگذارید، سوال بپرسید، و دیگران را به اشتراک گذاری افکار و ایده هایشان تشویق کنید. هر عضو تیم می تواند سهم ارزنده ای از سندی که شما تولید کرده اید داشته باشد.
یک نویسنده فنی استخدام کنید
در صورت امکان، استخدام کارمندی که از مستندات شما مراقبت کند، با ارزش می باشد. شخصی که معمولا این شغل را دارد، نویسنده فنی نامیده می شود. یک نویسنده فنی با پس زمینه مهندسی می تواند اطلاعات را از توسعه دهندگان بدون نیاز کسی که جزییات را برایش شرح دهد که چه کاری انجام می شود، جمع آوری کند. همچنین ارزش این را دارد که یک نویسنده فنی را به عنوان عضی از تیم بنشانید واو را در دفتر یکسانی قرار دهید تا همکاری نزدیکی برقرار کند. او قادر خواهد بود در جلسات و بحث های رایج مشارکت داشته باشد.
از cross-links استفاده کنید
از پیوندهای متقابل بین اسناد استفاده کنید، خواه صفحات محصول باشند یا راهنماهای کاربر. پیمایش مناسب از طریق مستندات شما برای دادن درک درست از موضوع به خواننده ، مهم می باشد. چنین عملی را می توان جریان-کاربر در نظر گرفت، اما برای مستندات پروژه شما.
واژه نامه ها(glossaries) را نادیده نگیرید
مستندات را می توان به استفاده داخلی یا خارجی اختصاص داد. در مورد اسناد خارجی، بهتر است که توضیح واضحی برای هر واژه در نظر گرفته شود و به معنی مختص آن در پروژه اشاره شود. مستندات باید ایده ها را با زبانی روشن و واضح مراوده کند تا زبان بین المللی-lingua franca (گویش مختلط ) بین ذینفعان و اعضای داخلی وکاربران تنظیم کند.
حرف آخر
روش چابک، تیم مهندسین را همواره به تمرکز روی ارزش های تحویل به مشتری شان تشویق می کند. این اصل مهم باید همچنین در فرآیند تولید مستندات نرم افزار در نظر گرفته شود. همواره مستندات نرم افزاری خوبی باید فراهم شود، خواه سند ویژگی های نرم افزار برای برنامه نویسان باشد یا دستورالعمل های نرم افزار برای کاربران. مستندات جامع نرم افزار، خاص، مختصر و وابسته می باشد/
همانطور که در بالا اشاره کردیم، لازم نیست کل مجموعه اسنادی که در این مطلب اشاره شد را تولید کنید. شما فقط روی آن اسنادی که مستقیما در دستیابی به اهداف پروژه کمک می کند تمرکز کنید.
و تمام، ابتدا قصد داشتم برای این مطلب از چند تا مرجع استفاده کنم و مرجع اصلی اینجا باشد، منتهی اینقدر همین مقاله ای که الان اشاره کردم مستقل و کامل بود که قید دیگر مراجع رو زدم و صرفا همین مرجع رو ترجمه کردم و باقی مطالب رو گذاشتم برای ادامه این مبحث در مقالات آینده ان شاالله.
ممنون میشم در زمینه مستند سازی نرم افزار اگر تجربه ای داشتید همینجا در میون بگذارید تا هم من و هم باقی عزیزان استفاده کنند.