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

در این مقاله به این میپردازیم که مستند فنی(Technical Document) چیست، مخاطبین آن چه کسانی هستند، انواع آن چیست و چارچوب کلی مستندات فنی چیست. همچنین به جزئیات سند SRS (Software Requirement Specification) میپردازیم.

مستندات فنی یعنی چه؟

مستندات فنی(Technical Documentation)، همه چیز مربوط به محصول یا نرم افزار شما را توضیح می دهند. می توانید آن را برای افراد داخل و خارج از سازمان خود بنویسید و بسته به خواننده، اسناد فنی شما نیازهای متفاوتی را برآورده می کند.

 

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

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

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

انواع مستندات فنی (به همراه مثال)

ما می توانیم آنها را به دو گروه اصلی تقسیم کنیم – اسناد فرآیند(Process documentation) و مستندات محصول(Product documentation).

اسناد فرآیند

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

انواعی از آن:

  • نقشه های پروژه
  • Product requirements documentation (PRD) -> SRS
  • نقشه راه محصول
  • درخواست نظرات (RFC):

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

  • مختصر فنی – Technical brief:

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

  • اسناد سیستم طراحی – Design system documentation:

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

  • مستندات کد منبع – Source code documentation:

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

اسناد محصول

  • Product manuals
  • User guides
  • FAQs
  • Wikis
  • API documentation

چگونه می توانیم میزان مستند بودن یک کد منبع را اندازه گیری کنیم؟

اندازه‌گیری میزان مستند بودن یک کد منبع می‌تواند نسبی باشد، اما برخی معیارها و روش‌های رایج وجود دارد که می‌تواند به ارزیابی کیفیت اسناد کمک کند:

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

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

  • ثبات – Consistency:

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

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

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

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

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

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

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

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

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

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

محتویات سند SRS

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

  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).

[2] A. Krosel, “What Is Technical Documentation?(And How To Create It),” Indeed, https://www.indeed.com/career-advice/career-development/technical-documentation (accessed 2024).

[3] Some parts are written with the help of chatGPT3.5-turbo

 
پیمایش به بالا