یکی از مهمترین قسمت های طراحی یک محصول که باید به آن پرداخته شود، مستندات اون محصول هست. این قسمت همیشه کمتر از باقی قسمت ها بهش ارزش و بها داده میشه در صورتی که جز پایه ای ترین قسمت های انجام یک پروژه است. مقاله ای که در ادامه مطالعه می کنید سعی در توضیح و ارایه انواع روش های مستند نویسی داره که کمک میکنه دید بهتری به فرایند و دلایل مستند نویسی پیدا کنیم.
کاغذبازی و انجام کارهای متفرقه، می تواند باعث حواس پرتی از کار واقعی شما باشد. با این حال، مستندات نرم افزار در مهندسی نرم افزار، بخش اساسی نوشتن یک کد خوب (clean code) و در نهایت یک محصول خوب است. اصلا مهم نیست که چقدر واضح و ساده فکر می کنید و یا از نرم افزار خود استفاده می کنید یا خیر، به عنوان یک برنامه نویس می دانید که باید برخی از انواع مستندات برنامه خود را ارائه دهید و اگر مستندی در دسترس نباشد، برنامه نویسان دیگر و یا کاربران نهایی نرم افزار ممکن است از برنامه های شما دست بکشند و به جستجوی نرم افزارهایی که همراه با دستورالعمل های مناسب و نحوه استفاده مشخص هستند، بپردازند.
انواع مستندات مختلف یک هدف را دنبال می کنند و آن هم این است که کاربران یک نرم افزار با استفاده از آن، نرم افزار را ساده تر درک کنند و از آن برای انجام کاری در سیستم استفاده کنند.
در اینجا کلمه کاربران، شامل کسانی که شاغل در آن سیستم هستند نیز می شود. اگر شرکتی که در آن شاغل هستید، از نرم افزار خاصی استفاده می کند، ارائه مستندات مختلف به کارمندانش باعث می شود که سریعتر در قالب سیستم قرار گیرند و در شرایط مختلف فعالیت (act) یکسانی داشته باشند.
ارائه مستندات کاربری مزایای دیگری را نیز داراست:
شما کارهایی که انجام داده اید را در ذهن خود دارید، اما شش ماه یا یک سال بعد از آن و انجام کار روی بخش های دیگر و یا پروژه های دیگر ممکن است برخی از خاطرات شما از بین رفته باشند. مستندات کاربر در آینده به شما و یا دیگر استفاده کنندگان کمک می کند تا بدون تکیه بر حافظه شما و یا دیگران از کارهای انجام شده گذشته هر فرد، استفاده صحیح شود.
می دانید که کاربران تجربه کار مداوم با نرم افزار را دارند، پس اطلاعات هر فرد ممکن است بر اساس تغییرات در نرم افزار نیز تغییر کند. داشتن مستندات، روال این تغییرات و دلیل آن را برای استفاده کنندگان مشخص می کند.
ارائه انواع صحیح مستندات برنامه جهت نشان دادن اینکه چقدر شما برای مشتریان و کارمندان ارزش قائل هستید، باعث بالا رفتن ارزش برند شما و ارتقا آن می شود. (value attribution)
اگر تنها کسی هستید که نرم افزار خود را درک می کند، احتمالاً تنها فردی هستید که از آن استفاده می کند یا توسعه می بخشید. این باعث رضایت شماست؟
اگر شخص دیگری باید روی کد شما با بروز رسانی یا تجدید نظر در آن کار کند، مستندات خوب باعث ساده و روانتر شدن روال انجام آن می شود.
توسعه دهندگان خوب، نوع و ارزش مستندات مختلف را می دانند و می دانند هر کدام چه نقش و کارایی دارند که در ادامه به هر کدام اشاره هایی می شود:
راهنمای کاربر (User manuals)
این مستندات در مورد بخشی از نرم افزار است که چگونه کاربران می توانند با آن کار کنند و بخش های مختلف نرم افزار را توضیح می دهد.این بخش حاوی توضیح واضح و دقیق است اینکه چگونه نرم افزار را نصب می کنید؟ چگونه می توانید یک پرونده را تبدیل کنید؟ آیا می توانید تصاویر اضافه کنید؟ چگونه یک خطا را تصحیح می کنید؟ حتی اگر راه حل ساده و تنها با کلیک بر روی نوار ابزار یا منو باشد، البته ممکن است کلیک های بالقوه زیادی وجود داشته باشد که از طریق توضیحات می توان آن را از بین برد. مستندات خوب برای کاربر می تواند کار آن را آسانتر کند.
مستندات کلی پروژه (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)
این موارد می توانند موضوعات اضافه شده ای را که فکر می کنید ارزش بحث عمیق تر را دارند، پوشش دهند. دلایلی که از روش خاص در بخش فنی و یا ساختار نرم افزار استفاده کرده اید و یا شرایطی که در قسمت های مختلف نرم افزار در نظر گرفته شده است، باشند.
معمولا صاحبان بیزینس، مدیران و برنامه نویسان ارشد، اهمیت داشتن مستندات بروز نرم افزاری را می دانند. کسانی که در پروژه های مختلف کار کرده اند می دانند چالش های زیادی در زمان ورود و خروج نیروی های جدید و قدیمی در شرکت ها و پروژه ها وجود دارد. زمان تطبیق پیدا کردن نیروی کاری یکی از این نوع چالش هاست که بسته به وجود اطلاعات و مستندات لازم پروژه در بخش های مختلف می تواند کوتاه و بلند باشد و هزینه های مادی و معنوی آن کم و یا زیاد باشد.
اگر شما در حال نوشتن یک نرم افزار و یا قسمتی از یک آن (طرح ها، افزونه ها و ...) به تنهایی هستید، مشخص است که خودتان اقدام به نوشتن مستندات آن می کنید، اگر می خواهید آن را در جامعه اپن سرس منتشر کنید، حتما می دانید، برای اقبال بیشتر نرم افزار، داشتن مستندات خوب و قابل استناد، شانس استفاده از نرم افزار شما را بالا می برد.
خوب مستند بنویسیم
این بخش یکی از تاثیرگذارترین بخش های مستند نویسی است. مهم نیست در کدام بخش از انوع مستندات می خواهید اقدام به نوشتن کنید، هدف و انگیزه شما از مستند نویسی باید به شکلی روشن، خواندنی و مفید باشد. چندین نکته وجود دارد که باید در خاطر داشته باشید:
پیدا کردن انواع اسناد کاربری که نوشته اید را آسان کنید. به عنوان مثال، می توانید پرونده ReadMe را به گره (node) اصلی تبدیل کنید که از آن کاربران می توانند تمام سطوح مختلف اسناد را پیدا و کشف کنند، قابلیت جستجو در مستندات نیز یکی دیگر از کارهایی است که می تواند دسترسی به اسناد را آسان نماید.
هر زمان که کار (کد، طرح، پترن، تنظیمات و...) خود را به روز می کنید، مستندات خود را نیز به روز کنید.
مراقب اشکالات باشید. مستندات را به طور کامل بررسی و تست کنید و هر نمونه کدی را که در آن قرار دارد، امتحان کنید. اگر مشکل پیدا کردید، آنها را برطرف کنید.
خوب بنویسید! شما می خواهید مستندات واضح، قابل فهم و پیگیری آسان باشد. خواندن اسناد و مدارک خود را با نوشتن کلمات سنگین، سخت نکنید. حتی در نوشتن فنی، نگارش به صورت صدای انسان باعث می شود خوانندگان راحت تر متوجه مطلب شوند. به عنوان مثال: اینجا می خوام در مورد این متد کمی توضیح بدم، این متد دو پارامتر ورودی داره که باعث میشه....
محصول خود را چقدر خوب می شناسید؟ اگر این نرم افزار یک تلاش تیمی است، تا زمانی که راضی شوید که تمام ویژگی ها را درک می کنید، با این نرم افزار کار کنید. اگر ویژگی های نرم افزار را نمی دانید، نوشتن در مورد نحوه استفاده از آنها دشوار خواهد بود و بعضا باعث گمراهی دیگران می شود.
نگاه به یک سند به راحتی خواندن آن تأثیر می گذارد. بلوک های طولانی از متن بدون هیچ گونه جدا سازی چشم خواننده را اذیت می کند. متن را با پاراگراف ها، نمودارها و تصاویر شکسته کنید.
مختصر و مفید باشید. مطمئنا شما نمی خواهید از هر چیز مهمی پرش کنید و جا بگذارید، اما خوانندگان از سرعت رسیدن شما به این موارد مهم، قدردانی می کنند.
وسایل دیداری اضافه کنید. عکسهای صفحه و دستورالعمل های ویدئویی معمولاً از ابزارهای آموزشی بهتری نسبت به متن هستند. داشتن نمودار های مختلف و تصویر سازی کمک بزرگی به شناخت سریعتر و بهتر خواننده نسبت به نرم افزار شما می کنند.
در عصر اینترنت، شما دیگر لازم نیست که با یک پرونده ReadMe خود را محدود کنید. می توانید بخشی برای اضافه شدن مستندات برنامه در وب سایت خود ارائه دهید. این کار مخصوصا برای رضایت کاربران نهایی بسیار تاثیر گذار است. در بخش مستندات فنی می توانید از wiki های موجود در سرویس های نگهداری سرس کدهای خود مانند gitlab و github و ... استفاده کنید.
اگر سرویس شما شامل یک وبلاگ نیز می شود، می توانید برای بحث درباره قابلیت های جدید نرم افزار و کارهایی که در حال انجام هستید، از آن استفاده کنید و اطلاع رسانی کنید.
چنانچه کاربران نهایی در استفاده از نرم افزار شما سؤال های مشابه می کنند، آنها را به لیست سؤالات متداول آنلاین ارجاع دهید. این کار به شما کمک می کند تا در مواجه با موارد نادر و غیر تکراری زمان بیشتری داشته باشید و در وقت شما صرفه جویی می کند. شما می توانید در ادامه سوالات متداول خود را به روز نگه دارید و متوجه می شوید در بازه زمانی مشخص نمودار سوالات کاربران از شما به صورت نزولی پیش رفته است.
خوب است بدانید که حتی اگر مدیران سطوح مختلف پروژه، اسناد را ننویسند، باید بر آنها نظارت داشته باشند. خطاها در بخش های مختلف مستندات می توانند منجر به اشتباه کاربران دیگر در استفاده از همان مستندات شوند و یا اسنادی نهایی شوند که با دید و سیاست های صاحبان اصلی و ذینفعان (stakeholders) مطابقت ندارند.
برخی از مدیران قبل از پیشبرد پروژه، ترجیح می دهند اسناد دقیق تهیه كنند. این روش در صورتی مفید است که محصول از مفهومش در ابتدا تا به شکل نهایی، تغییرات زیادی نداشته باشد. در این بین اگر تغییراتی ایجاد شود، تیم باید برای به روزرسانی اسناد تلاش کند.
روش جایگزین دیگر، تولید اسناد فقط به موقع خودش است. بر روی نرم افزار کار کنید و سپس کارهایی را که انجام داده اید هنگام انجام مراحل بعدی، مستند سازی کنید. این کار به یک روش ترجیحی تبدیل شده است زیرا اولویت را بر روی انجام پروژه قرار می دهد و در صورت تغییر پروژه، مستندات بعد از آن بروز می مانند.
در پایان به یاد داشته باشید که مستند نویسی و تولید مستندات خوب، به خودی خود، یک محصول است!
منابع و اطلاعات بیشتر:
https://en.wikipedia.org/wiki/Software_documentation
https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f?gi=567d612dcdf4
https://gbksoft.com/blog/types-of-software-development-documentation/
https://www.divio.com/blog/documentation/
https://bizfluent.com/13657938/types-of-software-documentation
https://gbksoft.com/blog/types-of-software-development-documentation/
https://sokanacademy.com/blog/6646/%D9%87%D8%B4%D8%AA-%D9%82%D8%A7%D9%86%D9%88%D9%86-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%86%D9%88%D8%B4%D8%AA%D9%86-%D9%85%D8%B3%D8%AA%D9%86%D8%AF%D8%A7%D8%AA-%D8%AE%D9%88%D8%A8
https://medium.com/pminsider/the-dangers-of-documentation-b2504068a11f
