مدیریت دانش
در این سند
اصول بهاشتراکگذاری دانش
تیم ما از اصول اصلی زیر برای مدیریت دانش پیروی میکند:
- اولویت مستندات: دانش حیاتی باید مستند شود، نه فقط به صورت شفاهی به اشتراک گذاشته شود
- دسترسیپذیری: تمام دانش تیم باید به راحتی برای همه اعضای تیم قابل دسترسی باشد
- بهروزرسانی مستمر: مستندات باید همگام با پایگاه کد تکامل یابد
- اطلاعات زمینهای: شامل "چرایی" تصمیمها باشد، نه فقط "چهچیزی" و "چگونگی"
- قالب استاندارد: از الگوهای مستندسازی یکپارچه پیروی کنید
الزامات مستندسازی
مستندات کد
مطابق با استانداردهای کدنویسی جهانی، موارد زیر الزامی است:
- مستندسازی تمام متدها و توابع عمومی با PHPDoc/JSDoc
- اضافه کردن نظرات مناسب برای توضیح منطق پیچیده
- گنجاندن مثال برای عملکردهای پیچیده
- مستندسازی هرگونه رفتار غیربدیهی یا موارد خاص
- بهروزرسانی مستندات هنگام تغییر کد
مستندات معماری
- ایجاد و نگهداری نمودارهای معماری
- مستندسازی تعاملات سیستم و جریانهای داده
- توضیح تصمیمات کلیدی معماری با استفاده از سوابق تصمیمگیری معماری (ADRs)
- بهروزرسانی نمودارها هنگام تغییر معماری
مستندسازی فرآیندها
- مستندسازی گردش کار توسعه
- ایجاد راهنماهای راهاندازی برای اعضای جدید تیم
- نگهداری راهنماهای عیبیابی برای مسائل رایج
- مستندسازی فرآیندهای استقرار
مکانیزمهای انتقال دانش
برنامهنویسی جفتی
- برنامهریزی جلسات منظم برنامهنویسی جفتی
- چرخش جفتها برای توزیع دانش در سراسر تیم
- مستندسازی بینشهای بهدستآمده در طول برنامهنویسی جفتی
بازبینی کد
مطابق با پروتکلهای ارتباطی و استانداردهای کدنویسی جهانی:
- تمام کدها باید قبل از ادغام فرآیند بازبینی را طی کنند
- هر درخواست ادغام حداقل به 2 بازبین (شامل مدیر فنی) نیاز دارد
- پیروی از الگوی درخواست کشش تعیینشده
- رسیدگی به تمام نظرات بازبینی قبل از درخواست بازبینی مجدد
- استفاده از بازبینی کد به عنوان فرصتی برای اشتراکگذاری دانش
سخنرانیهای فنی داخلی
- برنامهریزی سخنرانیهای ماهانه در مورد موضوعات مرتبط
- ضبط جلسات برای اعضای تیمی که نمیتوانند حضور داشته باشند
- اشتراکگذاری اسلایدها و منابع پس از ارائهها
پلتفرمهای مستندسازی
مستندات مرتبط با کد
- فایلهای README: دستورالعملهای راهاندازی و استفاده اولیه
- نظرات درون خطی: توضیح منطق پیچیده
- PHPDoc/JSDoc: مستندات API
- OpenAPI/Swagger: مستندات REST API
مستندات پروژه
- Docusaurus: پایگاه دانش اصلی (این سایت)
- نمودارها: معماری سیستم و گردش کار
- کانفلوئنس: مستندات دقیق پروژه
فرآیند راهاندازی
اعضای جدید تیم باید این فرآیند کسب دانش را دنبال کنند:
- بررسی فایل README پروژه و دستورالعملهای راهاندازی
- مطالعه بخشهای کلیدی مستندات
- برنامهنویسی جفتی با اعضای باتجربه تیم
- شروع با وظایف کوچک و مستندشده
- به تدریج مسئولیتهای پیچیدهتر را بر عهده بگیرند
نگهداری مستندات
چرخه بازبینی
- بازبینی فصلی تمام مستندات
- بهروزرسانی اطلاعات منسوخشده
- بایگانی مستندات منسوخشده
- شناسایی شکافهای مستندسازی
مالکیت
- هر مؤلفه اصلی یک مالک مستندات اختصاصی دارد
- مالکان مسئول بهروز نگهداشتن بخش خود هستند
- تمام اعضای تیم میتوانند پیشنهاداتی برای بهبود هر مستنداتی ارائه دهند
پروتکل شکافهای دانش
هنگام شناسایی شکافهای دانش:
- شکاف را در کانال تلگرام مربوطه مستند کنید
- یک وظیفه برای رفع نیاز مستندسازی ایجاد کنید
- یک مالک برای ایجاد مستندات از دسترفته تعیین کنید
- مستندات جدید را بررسی و تأیید کنید
- با تیم به اشتراک بگذارید
یکپارچهسازی با استانداردهای کدنویسی
روشهای مدیریت دانش ما با استانداردهای کدنویسی جهانی در این موارد همسو است:
- قوانین نامگذاری: مستندات از همان اصطلاحشناسی کد استفاده میکند
- سازماندهی کد: ساختار مستندات منعکسکننده سازماندهی کد است
- ساختار فایل: ارجاعات مستندات از همان ساختار پایگاه کد پیروی میکنند
- الزامات مستندسازی: هر دو استاندارد بر مستندسازی کامل تأکید دارند
بهترین روشها
نوشتن مستندات مؤثر
- از زبانی روشن و مختصر استفاده کنید
- مثالها و موارد استفاده را بگنجانید
- در صورت لزوم تصاویر (نمودارها، تصاویر) اضافه کنید
- محتوا را با عناوین واضح ساختار دهید
- به مستندات مرتبط پیوند دهید
بهروز نگهداشتن مستندات
- بهروزرسانی مستندات را به عنوان بخشی از فرآیند توسعه قرار دهید
- بهروزرسانیهای مستندات را در درخواستهای کشش بگنجانید
- مستندات را در طول بازبینی کد بررسی کنید
- نگهداری منظم مستندات را برنامهریزی کنید