12 KiB
12 KiB
مشخصات درس‌نامه: مستندسازی فاخر، شناسنامه مخزن (README.md) و کتابچه راهنمای نگهداری (Runbooks)
- شناسه در سیلابس:
L13.7 - فصل: فصل ۱۳: نگهداری محصول (Ch 13)
- نوع محتوا: 📘 درس‌نامه متنی
- زمان تقریبی مطالعه: ۱۸ دقیقه
- پیش‌نیازهای مستقیم:
L13.6(سئو تکنیکال و تحلیل رفتار کاربر)
۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- درک کند (Understand): چرا کدی که مستندات نداشته باشد یک معماست نه یک محصول، و چگونه یک صفحه گیت‌هاب حرفه‌ای با
README.mdفاخر، اولین ویترین قضاوت مهندسی کارفرمایان و مدیران فنی است. - تحلیل/ارزیابی کند (Evaluate): ۶ بخش طلایی یک سند مستندات استاندارد (عنوان و بج‌های وضعیت، اسکرین‌شات‌ها، معماری سیستم، راهنمای راه‌اندازی محلی، پیکربندی متغیرها، و لایسنس) را ارزیابی کند.
- به‌کار ببندد (Apply): کتابچه‌های عملیاتی راهنمای بحران (Operational Runbooks) را برای سناریوهای اضطراری (نظیر اتمام شارژ پیامک، بازیابی پشتیبان دیتابیس، و تعویض کلیدها) تدوین نماید.
- ایجاد کند (Create): با هدایت ایجنت‌های هوش مصنوعی، مستندات کامل پروژه پورتفولیو را به همراه دیاگرام‌های Mermaid آماده رندر در گیت‌هاب تولید و منتشر کند.
۲. محدوده و مرزهای محتوا (Scope & Boundaries)
آنچه باید پوشش داده شود (In-Scope):
- داستان دو پروژه یکسان با دو سرنوشت متفاوت:
- پروژه‌ای عالی بدون داکیومنت که در گیت‌هاب خاک می‌خورد در برابر پروژه‌ای با بج‌های شکیل و داکیومنت جذاب که صدها ستاره می‌گیرد و مصاحبه‌کنندگان را مجذوب می‌کند.
- ارکان ۶ گانه یک
README.mdدر سطح استاندارد جهانی:- ۱. بخش هدر: عنوان، شعار تک‌خطی جذاب، بج‌های شیلدز (Shields.io: نسخه Next.js، لایسنس MIT، وضعیت استقرار).
- ۲. پیش‌نمایش بصری: اسکرین‌شات‌های باکیفیت یا تصاویر متحرک گیف از محیط لایو و پنل مدیریت.
- ۳. جعبه ابزار و پشته فناوری (Tech Stack): معرفی شفاف Next.js, Supabase, Tailwind, Kavenegar, Zarinpal, Sentry.
- ۴. معماری سیستم و نمودار جریان داده با فرمت Mermaid (رندر مستقیم داخل گیت‌هاب).
- ۵. راهنمای راه‌اندازی سریع گام‌به‌گام (Quickstart): کلون کردن، نصب پکیج‌ها، ساخت فایل
.envو دستور ران. - ۶. راهنمای استقرار، مشارکت (Contributing) و لایسنس.
- کتابچه راهنمای واکنش به بحران (Operational Runbooks / Playbooks):
- سناریوی ۱: اگر پیامک‌ها نرسید چه کنیم؟ (چک کردن شارژ کاوه‌نگار و لاگ‌های وب‌سرویس).
- سناریوی ۲: نحوه دریافت نسخه پشتیبان اضطراری از جداول دیتابیس در کنسول Supabase.
- سناریوی ۳: چرخه تعویض کلیدهای فاش‌شده بدون خاموش کردن سایت.
- تکنیک تولید و به‌روزرسانی مستندات با ایجنت‌های هوش مصنوعی:
- خوراندن ساختار فایل‌ها (
tree) وpackage.jsonبه ایجنت و دریافت داکیومنت ساختاریافته.
- خوراندن ساختار فایل‌ها (
- کال‌اوت‌های آموزشی و هشدار کوئرا:
- کال‌اوت بنفش (
<details class="violet">): قابلیت رندر مستقیم دیاگرام‌های Mermaid در ریپازیتوری‌های گیت‌هاب بدون نیاز به تصویر خارجی. - کال‌اوت سبز (
<details class="green">): استفاده از بج‌های رنگی Shields.io برای ایجاد حس محصولات متن‌باز سطح یک سیلیکون‌ولی. - کال‌اوت قرمز (
<details class="red">): هرگز مقادیر واقعی کلیدهای اختصاصی را داخل مثال‌هایREADME.mdکپی نکنید؛ همیشه از مقادیر فرضی استفاده نمایید.
- کال‌اوت بنفش (
آنچه نباید وارد آن شویم (Out-of-Scope):
- راه‌اندازی پورتال‌های مستندات بزرگ شرکتی مثل Docusaurus یا GitBook.
- تولید مستندات اتوماتیک API با ابزارهای Swagger/OpenAPI در سطح کدهای بک‌اند پیچیده.
۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|---|---|---|
| README.md | سند معرفی و راهنمای مخزن | فایل ورودی اصلی هر پروژه نرم‌افزاری که هویت، ویژگی‌ها و شیوه اجرای آن را معرفی می‌کند |
| Runbook / Playbook | کتابچه عملیاتی راهنمای بحران | دستورالعمل گام‌به‌گام مدون برای نگهداری دوره‌ای و واکنش سریع به حوادث و خطاهای سیستم |
| Shields.io Badges | نشان‌ها و بج‌های وضعیت | برچسب‌های گرافیکی متنی کوچک برای نمایش وضعیت بیلد، پلتفرم‌ها و نسخه‌ها در بالای مستندات |
| Quickstart Guide | راهنمای راه‌اندازی سریع | خلاصه دستورات ترمینالی ضروری برای اجرای پروژه در ۵ دقیقه توسط فرد تازه وارد |
| Mermaid in Markdown | نمودارهای درون‌خطی مرمید | رسم فلوچارت‌ها و ساختارهای گرافیکی با کدهای متنی ساده که مستقیماً در گیت‌هاب رندر می‌شوند |
۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ
images/ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
- تصویر کاور درس:
images/cover.png- موضوع: کتابچه بازشده نئونی مدرن با کدهای درخشان، برچسب‌های رنگارنگ و نماد تیک سبز استاندارد جهانی روی مانیتور گیت‌هاب.
- کالبدشکافی یک سند README فاخر در گیت‌هاب:
images/readme-anatomy-infographic.png- موضوع: اسکرین‌شات از صفحه مخزن گیت‌هاب با کادرهای نئونی دور بج‌ها، اسکرین‌شات سایت، جدول فیچرها، دیاگرام معماری و بخش Quickstart.
- نمودار معماری رندر شده با Mermaid در گیت‌هاب:
images/github-mermaid-architecture-render.png- موضوع: نمایش تصویری فلوچارت سیستم پورتفولیو که مستقیماً از کدهای متنی Markdown در گیت‌هاب رندر شده است.
- نمونه برگ کتابچه واکنش به بحران (Runbook Card):
images/operational-runbook-card-preview.png- موضوع: کارت مستند راهنمای بحران با عنوان «در صورت اتمام شارژ پیامک چه کنیم؟» با مراحل ۳ گانه ترتیبی و چک‌لیست سریع.
۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)
- تیتر اصلی:
# مستندسازی فاخر، شناسنامه مخزن (README.md) و کتابچه راهنمای نگهداری (Runbooks) - مقدمه: چرا یک مدیر فنی قبل از اینکه کدهای شما را ببیند، به
README.mdپروژه نگاه می‌کند و چطور در همان ثانیه اول او را شگفت‌زده کنیم؟ - جدول کاور درس
- استعاره تابلوی ورودی و بروشور راهنمای موزه:
- بدون راهنما، اشیای عتیقه فقط تکه‌های خاک‌خورده سنگ به نظر می‌رسند؛ مستندات ارزش کار شما را هویدا می‌کند.
- آناتومی ۶ ستون یک README در کلاس جهانی:
- نشان‌های شیک Shields.io، پیش‌نمایش‌های بصری، جدول استک، دیاگرام معماری، و بخش راه‌اندازی سریع.
- رسم جادویی دیاگرام‌های معماری با کدهای Mermaid:
- چرا نباید دیاگرام را با عکس‌های سنگین بگذاریم؟ نوشتن کدهای تمیز فلوچارت که در گیت‌هاب رندر می‌شوند.
- تدوین کتابچه‌های واکنش اضطراری به بحران (Operational Runbooks):
- ۳ سناریوی بحرانی در پروژه پورتفولیو و دستورالعمل مهار آن‌ها.
- جعبه پرامپت طلایی: ساخت شناسنامه کامل پروژه با ایجنت هوش مصنوعی:
- پرامپت دقیق:
«من می‌خواهم برای مخزن گیت‌هاب پورتفولیو یک فایل
README.mdفوق‌العاده شکیل، حرفه‌ای و جذاب بنویسم. پشته فناوری پروژه شامل Next.js 15، TypeScript، TailwindCSS، Supabase، Liara، ZarinPal، Kavenegar و Sentry است. لطفاً مستندی با بج‌های رنگی، جدول ویژگی‌ها، کد Mermaid فلوچارت سیستم، راهنمای گام‌به‌گام اجرای لوکال با متغیرهای فرضی، و راهنمای استقرار تدوین کن.»
- پرامپت دقیق:
- باکس نکته Quera (
<details class="violet">): استفاده از فایلCONTRIBUTING.mdبرای ایجاد حس یک پروژه اوپن‌سورس بالغ و آماده همکاری تیمی. - باکس هشدار Quera (
<details class="red">): هرگز کلیدهای معتبر را در بخش تنظیمات فایل‌های محیطی README نگذارید؛ همیشه از مقادیر مثلyour_key_hereاستفاده کنید. - باکس رضایت‌بخش Quera (
<details class="green">): ثبت دکمه Commit و باز کردن صفحه اصلی مخزن پورتفولیو در گیت‌هاب و تحسین نظم و زیبایی آن. - جمع‌بندی فصل سیزدهم و پرش به فصل پانزدهم: پایان کامل فاز نگهداری؛ یادآوری گذر از پروژه ۲ (فصل ۱۴) و پرتاب به سوی فصل جذاب پانزدهم: تکامل محصول با AI (بازنویسی کدها، ایجنت‌های خودکار، PWA و اپ موبایل/دسکتاپ).
۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- ارکان شش‌گانه یک
README.mdحرفه‌ای به همراه نمونه کدهای Markdown تشریح گردند. - نحوه ترسیم فلوچارت‌های سیستمی با فرمت Mermaid آموزش داده شود.
- مفهوم کتابچه‌های راهنمای عملیاتی (Runbooks) با سناریوهای پورتفولیو تبیین شود.
- پرامپت تولید خودکار مستندات جامع با ایجنت در متن درس لحاظ گردد.