الغرض
تتحرك الفرق الموزعة بشكل أسرع عندما يتم تدوين كتيبات التشغيل والقرارات والدروس بطرق يمكن التنبؤ بها. يوضح هذا الكتيب كيف نلتقط المعرفة حتى يظل التأهيل سلسًا، ولا يُحتجز السياق أبدًا في الرسائل المباشرة، ويمكن إعادة استخدام التشريحات اللاحقة كحواجز حماية مستقبلية.
مبادئ الكتابة
- الوضوح أولاً. استهدف لغة يمكن لزميل جديد في الفريق متابعتها في قراءة واحدة. قم بكسر المصطلحات عن طريق إضافة حواشي توضيحية أو إدخالات في المسرد.
- الدقة على السرعة. تحقق من البيانات والروابط والمالكين. يضيع مقتطف تكوين خاطئ وقتًا أطول من التحديث المتأخر.
- هيكل موجز. اجعل الفقرات قصيرة، وفضل القوائم النقطية، واستخدم وسائل الشرح للتحذيرات أو النصائح الهامة.
- مراعاة الجمهور. قم بتخصيص المستندات للدور المقصود. يجب أن يسلط دليل الميسر الضوء على الأدوات والتوقيتات وأنماط الفشل، بينما يجب أن يعرض دليل التشغيل الأوامر وخطوات التراجع.
- إصدار وملكية. تسرد كل صفحة تاريخ “التحديث” ومالكًا مسؤولاً عن إبقائها حية.
دورة حياة التوثيق
تعامل مع التوثيق كحلقة مستمرة تظلل دورة حياة تطوير البرمجيات الخاصة بك. تحافظ دورة حياة تطوير التوثيق الخفيفة (DDLC) على تحديث المحتوى:
graph TD
A[التخطيط] --> B(التحليل)
B --> C{تطوير المحتوى}
C --> D[المراجعة والتحرير]
D --> E(النشر)
E --> F[الصيانة والتحديثات]
F --> A
- التخطيط: حدد النطاق والجمهور وقناة النشر. قم بإقران مستند بنتيجة قابلة للقياس (على سبيل المثال، تقليل وقت التأهيل).
- التحليل: قم بإجراء مقابلات مع خبراء الموضوع، ومراجعة المقاييس، وجمع لقطات الشاشة أو صادرات البيانات.
- تطوير المحتوى: قم بصياغة المستند باستخدام القوالب المشتركة. قم بتضمين الرسوم البيانية باستخدام Mermaid حيث تكون وضوح التدفق مهمًا.
- المراجعة والتحرير: قم بتوجيه المسودات من خلال نظير واحد على الأقل ومالك مسؤول واحد للدقة والنبرة.
- النشر: الشحن عبر موقع التوثيق المشترك، مع وضع علامات على الصفحة حتى تظهر في البحث والتنقل في الشريط الجانبي.
- الصيانة: جدولة المراجعات ربع السنوية. أرشفة أو دمج الصفحات القديمة لمنع انحراف المعرفة.
الأدوات في مجموعتنا
- التأليف الذي يركز على Markdown: اكتب في VS Code أو بوابة المستندات، مع الحفاظ على التنسيق بسيطًا وسهل المقارنة.
- النشر الثابت: يقدم Astro + Starlight صفحات سريعة وقابلة للبحث مع تنقل مدمج.
- الرسم البياني: تفضل Mermaid للهندسة المعمارية وسير العمل وأشجار القرار حتى تظل التحديثات في التحكم في الإصدار.
- التحكم في الإصدار: توضع جميع المستندات بجانب التعليمات البرمجية في Git لإعادة استخدام مهام سير المراجعة المألوفة.
طرحه
- قدم الكتيب أثناء تأهيل الفريق واستعراضات السباق.
- قم بإقران المعايير بقوالب لكتيبات التشغيل والقرارات ومراجعات الحوادث.
- تتبع “وقت الوصول إلى السياق” (المدة التي يحتاجها زميل في الفريق للارتقاء) وقم بتحديث الكتيب عند ظهور الاحتكاك.
- احتفل بالمساهمات علنًا حتى يتم تقييم عمل التوثيق جنبًا إلى جنب مع ميزات الشحن.