المساهمة في توثيق Nibleaf

تستخدم تغييرات التوثيق سير عمل طلب السحب نفسه الذي تستخدمه الشيفرة. يجعل مصدر المستودع المحتوى قابلًا للمراجعة؛ ولا يتغير الموقع الأساسي إلا بعد استيراد المصدر المعتمد أو مزامنته، ثم نشره والتحقق منه.

اختيار قارئ واحد وغرض واحد

قبل الكتابة، حدّد هدف القارئ واختر نوع محتوى واحدًا:

• برنامج تعليمي لتحقيق أول نجاح موجه؛
• دليل إجرائي لمهمة محددة؛
• مرجع لحقائق سهلة الاستعراض؛
• شرح للمفاهيم والقرارات.

قسّم الصفحات التي تحاول في الوقت نفسه تعليم مبتدئ، واستكشاف عطل وإصلاحه، وسرد كل إعداد. استخدم المصطلحات الظاهرة في Nibleaf والكلمات التي يستخدمها القرّاء في الدعم والبحث.

التحقق من ادعاءات المنتج

اقرأ التنفيذ، وملفات أمثلة البيئة، وملفات Compose، والاختبارات، وملاحظات الإصدار التي تحكم سير العمل. نفّذ الأوامر في بيئة مطابقة متى كان ذلك عمليًا. إذا كان الادعاء لا ينطبق إلا على main أو ميزة تجريبية أو إصدار مستقبلي، فاذكر ذلك بدلًا من عرضه بوصفه متاحًا عمومًا.

لا تنسخ صياغة توثيق مملوك. يمكن للأدلة الخارجية أن تساعد في المنهج والبنية؛ لكن مستودع Nibleaf هو الذي يحدد حقيقة المنتج.

كتابة صفحة مكتفية بذاتها

ابدأ بالنتيجة. ضع المتطلبات الأساسية قبل الخطوات، واجعل كل خطوة تحتوي إجراءً واحدًا، واعرض النتائج المتوقعة، وأضف طريقة تعافٍ للأعطال المحتملة. استخدم عناوين H2 وH3 واضحة، وروابط وصفية، وأسوار شيفرة موسومة باللغة، ونصوصًا بديلة ذات معنى للصور، وتسميات واجهة مطابقة تمامًا.

تتطلب كل صفحة الحقول title وdescription وaudience وcontent_type وlast_reviewed وverified_against في البيانات الوصفية الأمامية. أضفها إلى docs.json؛ ولا تترك صفحة قابلة للتنقل يتيمة.

التحقق والمراجعة

شغّل:

pnpm docs:check
pnpm --filter @nibleaf/app build

لسير عمل ظاهر للمستخدم، عاين عروضًا تمثيلية لسطح المكتب والهاتف المحمول. لا تستخدم لقطة شاشة إلا عندما توضح حالة يصعب العثور عليها أو تثبت التخطيط؛ واجعل التعليمات المكتوبة كافية من دونها. احجب الحسابات والرموز ومحتوى العملاء وتفاصيل البنية التحتية.

ينبغي أن يذكر طلب السحب مشكلة القارئ، والمسارات المتغيرة، والأوامر والمصادر التي جرى التحقق منها، ونتائج الاختبارات، والدليل المرئي، وحدود المنتج، وأي فجوة متبقية.

النشر والصيانة

بعد المراجعة، استورد المصدر أو زامنه مع مشروع Nibleaf الرسمي، وانشر إصدارًا واحدًا متسقًا، واختبر الموقع الأساسي في أثناء تسجيل الخروج. تحقق من صفحة عميقة، والبحث، وصفحة 404، والرابط الأساسي، وخريطة الموقع، وllms.txt، والتنقل على الهاتف المحمول، وعمليات إعادة التوجيه المتغيرة.

استخدم تحليلات التوثيق، وعمليات البحث بلا نتائج، وأسئلة الدعم، وتغييرات المنتج، وملاحظات القرّاء لبدء مراجعات مركزة. أزل التعليمات المضللة أو صححها سريعًا؛ فالتوثيق التشغيلي الخاطئ أسوأ من قيد صريح.