مستند فنی چیست و چگونه آنرا بنویسیم؟

• پوشش اسناد – Documentation coverage:
  یکی از راه‌های اندازه‌گیری کیفیت اسناد، ارزیابی میزان مستند بودن کد است. ابزارهایی مانند Doxygen یا Javadoc می توانند گزارش های پوشش اسنادی را بر اساس نظرات موجود در کد ایجاد کنند.
• وضوح و خوانایی:

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

• ثبات – Consistency:

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

• مرتبط بودن – Relevance:

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

• مثال‌ها و موارد استفاده – Examples and use cases:

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

• نظرات و حاشیه نویسی – Comments and annotations:

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

• ابزار مستند سازی:

  استفاده از ابزارهای مستندسازی و مولدها می تواند به خودکارسازی فرآیند ایجاد و نگهداری اسناد کمک کند. ابزارهایی مانند فایل‌های Sphinx، MkDocs یا README در قالب Markdown می‌توانند به‌روز نگه‌داشتن اسناد را آسان‌تر کنند.

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

1. واژه نامه – Glossary: شامل واژه نامه ای از اصطلاحات مورد استفاده در سراسر سند برای اطمینان از درک مشترک از اصطلاحات است.
2. مقدمه:
   این بخش یک نمای کلی از سند شامل هدف، محدوده و اهداف پروژه نرم افزار ارائه می دهد.
3. محدوده – Scope:
   حوزه و محدوده‌ی یک پروژه‌ی نرم افزاری را توصیف می‌کند، از جمله اینکه پروژه شامل چه چیز هایی می‌شود و شامل چه چیز هایی نمی‌شود. دقت داشته باشید که در فلسفه‌ی نرم افزار، همیشه همیشه آن چیز که نیست مهم تر از آن چیز که هست است. پس با دقت به این بپردازید که پروژه، چه چیزی نیست و شامل چه چیز هایی نمی‌شود.
4. نیازهای عملکردی – Functional requirements:

   الزامات عملکردی سیستم نرم افزار، از جمله ویژگی های خاص، قابلیت ها و تعاملات با کاربران و سایر سیستم‌ها را به تفصیل بیان می کند؛ مقادیری که قابل اندازه گیری نیستند. برای مثال:

   1. این سیستم باید به کاربران اجازه ایجاد یک حساب کاربری جدید را بدهد.
   2. این سیستم باید یک قابلیت جستجو را فراهم کند تا کاربران بتوانند محصولات را پیدا کنند.
   3. کاربری سیستم باید برای افراد مسن ساده باشد
5. نیازهای غیر عملکردی – Non-functional requirements:

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

   1. سیستم باید کمتر از 2 ثانیه زمان پاسخگویی برای پرس و جوهای جستجو داشته باشد.
   2. این سیستم باید برای کاربران دارای معلولیت طبق استانداردهای WCAG 2.0 قابل دسترسی باشد.
   3. این سیستم باید بتواند حداقل 1000 کاربر همزمان را بدون کاهش عملکرد مدیریت کند.
6. نیازهای کاربر – User requirements:
   الزامات را از دیدگاه کاربران نهایی، از جمله رابط های کاربری، نقش های کاربر، و تعاملات کاربر مشخص می کند.
7. نیازهای سیستم – System requirements:
   سخت افزار، نرم افزار و شبکه مورد نیاز برای پشتیبانی از سیستم نرم افزاری را تشریح می کند.
8. کاربری‌ها – Use cases:
   توضیحات مفصلی از موارد یا سناریوهای استفاده خاص ارائه می دهد که نحوه تعامل کاربران با سیستم نرم افزاری را نشان می دهد. یک روش برای این کار ساختن سیرِ کاربری (User journey) با استفاده از wireframe ها است.
9. داده‌های مورد نیاز – Data requirements:
   الزامات داده سیستم نرم افزاری، از جمله منابع داده، فرمت های داده و الزامات ذخیره سازی داده را شرح می دهد.
10. مفروضات و محدودیت‌ها – Assumptions and constraints:
    هر گونه فرضی که در طول فرآیند جمع آوری نیازمندی‌ها و محدودیت هایی که ممکن است بر توسعه سیستم نرم افزار تأثیر بگذارد را فهرست می کند.
11. وابستگی – Dependencies:
    هر گونه وابستگی خارجی یا مؤلفه های شخص ثالثی را که سیستم نرم افزاری به آنها متکی است، شناسایی می کند.
12. معیارهای پذیرش – Acceptance criteria: معیارهایی را تعریف می کند که برای پذیرفته شدن سیستم نرم افزاری توسط ذینفعان باید رعایت شود.

این بخش‌ها یک چارچوب ساختار یافته برای ثبت و سازماندهی نیازمندی های یک سیستم نرم افزاری در یک سند SRS ارائه می کنند. تطبیق سند با نیازهای خاص پروژه و ذینفعان برای اطمینان از اینکه همه الزامات مربوطه به طور مؤثر درک و ابلاغ می شوند، مهم است.

[1] S. Ashby, “How to write technical documentation – with examples,” gitbook, https://www.gitbook.com/blog/how-to-write-technical-documentation-with-examples (accessed 2024).