102 lines
12 KiB
Markdown
102 lines
12 KiB
Markdown
# مشخصات درس‌نامه: مستندسازی فاخر، شناسنامه مخزن (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):
|
||
1. **داستان دو پروژه یکسان با دو سرنوشت متفاوت:**
|
||
* پروژه‌ای عالی بدون داکیومنت که در گیت‌هاب خاک می‌خورد در برابر پروژه‌ای با بج‌های شکیل و داکیومنت جذاب که صدها ستاره می‌گیرد و مصاحبه‌کنندگان را مجذوب می‌کند.
|
||
2. **ارکان ۶ گانه یک `README.md` در سطح استاندارد جهانی:**
|
||
* ۱. بخش هدر: عنوان، شعار تک‌خطی جذاب، بج‌های شیلدز (Shields.io: نسخه Next.js، لایسنس MIT، وضعیت استقرار).
|
||
* ۲. پیش‌نمایش بصری: اسکرین‌شات‌های باکیفیت یا تصاویر متحرک گیف از محیط لایو و پنل مدیریت.
|
||
* ۳. جعبه ابزار و پشته فناوری (Tech Stack): معرفی شفاف Next.js, Supabase, Tailwind, Kavenegar, Zarinpal, Sentry.
|
||
* ۴. معماری سیستم و نمودار جریان داده با فرمت Mermaid (رندر مستقیم داخل گیت‌هاب).
|
||
* ۵. راهنمای راه‌اندازی سریع گام‌به‌گام (Quickstart): کلون کردن، نصب پکیج‌ها، ساخت فایل `.env` و دستور ران.
|
||
* ۶. راهنمای استقرار، مشارکت (Contributing) و لایسنس.
|
||
3. **کتابچه راهنمای واکنش به بحران (Operational Runbooks / Playbooks):**
|
||
* سناریوی ۱: اگر پیامک‌ها نرسید چه کنیم؟ (چک کردن شارژ کاوه‌نگار و لاگ‌های وب‌سرویس).
|
||
* سناریوی ۲: نحوه دریافت نسخه پشتیبان اضطراری از جداول دیتابیس در کنسول Supabase.
|
||
* سناریوی ۳: چرخه تعویض کلیدهای فاش‌شده بدون خاموش کردن سایت.
|
||
4. **تکنیک تولید و به‌روزرسانی مستندات با ایجنت‌های هوش مصنوعی:**
|
||
* خوراندن ساختار فایل‌ها (`tree`) و `package.json` به ایجنت و دریافت داکیومنت ساختاریافته.
|
||
5. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<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/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** کتابچه بازشده نئونی مدرن با کدهای درخشان، برچسب‌های رنگارنگ و نماد تیک سبز استاندارد جهانی روی مانیتور گیت‌هاب.
|
||
2. **کالبدشکافی یک سند README فاخر در گیت‌هاب:** `images/readme-anatomy-infographic.png`
|
||
* **موضوع:** اسکرین‌شات از صفحه مخزن گیت‌هاب با کادرهای نئونی دور بج‌ها، اسکرین‌شات سایت، جدول فیچرها، دیاگرام معماری و بخش Quickstart.
|
||
3. **نمودار معماری رندر شده با Mermaid در گیت‌هاب:** `images/github-mermaid-architecture-render.png`
|
||
* **موضوع:** نمایش تصویری فلوچارت سیستم پورتفولیو که مستقیماً از کدهای متنی Markdown در گیت‌هاب رندر شده است.
|
||
4. **نمونه برگ کتابچه واکنش به بحران (Runbook Card):** `images/operational-runbook-card-preview.png`
|
||
* **موضوع:** کارت مستند راهنمای بحران با عنوان «در صورت اتمام شارژ پیامک چه کنیم؟» با مراحل ۳ گانه ترتیبی و چک‌لیست سریع.
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# مستندسازی فاخر، شناسنامه مخزن (README.md) و کتابچه راهنمای نگهداری (Runbooks)`
|
||
2. **مقدمه:** چرا یک مدیر فنی قبل از اینکه کدهای شما را ببیند، به `README.md` پروژه نگاه می‌کند و چطور در همان ثانیه اول او را شگفت‌زده کنیم؟
|
||
3. **جدول کاور درس**
|
||
4. **استعاره تابلوی ورودی و بروشور راهنمای موزه:**
|
||
* بدون راهنما، اشیای عتیقه فقط تکه‌های خاک‌خورده سنگ به نظر می‌رسند؛ مستندات ارزش کار شما را هویدا می‌کند.
|
||
5. **آناتومی ۶ ستون یک README در کلاس جهانی:**
|
||
* نشان‌های شیک Shields.io، پیش‌نمایش‌های بصری، جدول استک، دیاگرام معماری، و بخش راه‌اندازی سریع.
|
||
6. **رسم جادویی دیاگرام‌های معماری با کدهای Mermaid:**
|
||
* چرا نباید دیاگرام را با عکس‌های سنگین بگذاریم؟ نوشتن کدهای تمیز فلوچارت که در گیت‌هاب رندر می‌شوند.
|
||
7. **تدوین کتابچه‌های واکنش اضطراری به بحران (Operational Runbooks):**
|
||
* ۳ سناریوی بحرانی در پروژه پورتفولیو و دستورالعمل مهار آن‌ها.
|
||
8. **جعبه پرامپت طلایی: ساخت شناسنامه کامل پروژه با ایجنت هوش مصنوعی:**
|
||
* پرامپت دقیق:
|
||
> «من می‌خواهم برای مخزن گیت‌هاب پورتفولیو یک فایل `README.md` فوق‌العاده شکیل، حرفه‌ای و جذاب بنویسم. پشته فناوری پروژه شامل Next.js 15، TypeScript، TailwindCSS، Supabase، Liara، ZarinPal، Kavenegar و Sentry است. لطفاً مستندی با بج‌های رنگی، جدول ویژگی‌ها، کد Mermaid فلوچارت سیستم، راهنمای گام‌به‌گام اجرای لوکال با متغیرهای فرضی، و راهنمای استقرار تدوین کن.»
|
||
9. **باکس نکته Quera (`<details class="violet">`):** استفاده از فایل `CONTRIBUTING.md` برای ایجاد حس یک پروژه اوپن‌سورس بالغ و آماده همکاری تیمی.
|
||
10. **باکس هشدار Quera (`<details class="red">`):** هرگز کلیدهای معتبر را در بخش تنظیمات فایل‌های محیطی README نگذارید؛ همیشه از مقادیر مثل `your_key_here` استفاده کنید.
|
||
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** ثبت دکمه Commit و باز کردن صفحه اصلی مخزن پورتفولیو در گیت‌هاب و تحسین نظم و زیبایی آن.
|
||
12. **جمع‌بندی فصل سیزدهم و پرش به فصل پانزدهم:** پایان کامل فاز نگهداری؛ یادآوری گذر از پروژه ۲ (فصل ۱۴) و پرتاب به سوی فصل جذاب پانزدهم: تکامل محصول با AI (بازنویسی کدها، ایجنت‌های خودکار، PWA و اپ موبایل/دسکتاپ).
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] ارکان شش‌گانه یک `README.md` حرفه‌ای به همراه نمونه کدهای Markdown تشریح گردند.
|
||
- [ ] نحوه ترسیم فلوچارت‌های سیستمی با فرمت Mermaid آموزش داده شود.
|
||
- [ ] مفهوم کتابچه‌های راهنمای عملیاتی (Runbooks) با سناریوهای پورتفولیو تبیین شود.
|
||
- [ ] پرامپت تولید خودکار مستندات جامع با ایجنت در متن درس لحاظ گردد.
|