كتابة توثيق إرشادي فعال

[Discourse]

يوفّر هذا الدليل تعليمات حول كتابة أدلة “كيف” فعّالة لمنصة Discourse. يغطي العناصر الأساسية مثل الهيكل والأسلوب، ومراعاة الجمهور المستهدف، والصيانة.

مستوى المستخدم المطلوب: يمكن لأي شخص كتابة أدلة “كيف” جديدة

إن كتابة أدلة “كيف” فعّالة أمر بالغ الأهمية لمساعدة المستخدمين والمشرفين والمسؤولين ومسؤولي الأنظمة على أداء مهام متنوعة داخل منصة Discourse. سيساعدك هذا الدليل في صياغة أدلة “كيف” واضحة وقيّمة للمجتمع.

ملخص

في هذا الدليل، ستتعلم:

• لماذا يُعدّ كتابة دليل “كيف” أمرًا مهمًا
• ما هي المعلومات التي يجب تضمينها
• إرشادات حول الهيكل والأسلوب
• أين يتم نشر هذه المواضيع
• كيفية صيانتها بعد النشر

لماذا نكتب دليل “كيف”؟

هل واجهت يومًا مهمة تحتاج إلى إنجازها ونسيت كيفية القيام بها؟ يُعدّ كتابة وثيقة “كيف” طريقة ممتازة لتوثيق العمليات في منصة Discourse. إذا كنت تواجه صعوبة في عملية معينة، فمن المرجّح أن يكون شخص آخر يعاني من نفس المشكلة. توثيق هذه العملية يفيد الجميع.

تعرّف أكثر على ما يميّز دليل “كيف” عن أنواع التوثيق الأخرى مثل الدروس التوجيهية أو أدلة المراجع في هذا الدليل من Divio.

إن كتابة أو مراجعة دليل “كيف” هي طريقة رائعة للمساهمة بمعرفة حول منصة Discourse في المجتمع. لمعرفة طرق أخرى للمساهمة، اطلع على دليل كيفية المساهمة في Discourse.

ما هي المعلومات التي يجب تضمينها؟

يجب أن يكون دليل “كيف” دليلًا خطوة بخطوة يوجّه المستخدم نحو نتيجة نهائية محددة. على سبيل المثال، يجب أن يوفر دليل بعنوان “إعداد HTTPS لمنصة Discourse” تعليمات لإعداد HTTPS.

نقاط رئيسية يجب تذكرها عند كتابة دليل “كيف”:

• التزم بالموضوع وكن واضحًا
• تجنّب المعلومات غير الضرورية
• كن موجزًا مع الحفاظ على الإفادة
• اشرح لماذا تحقيق النتيجة النهائية مفيد

ضع جمهورك المستهدف في اعتبارك

هناك جماهير مختلفة لأدلة “كيف” الخاصة بمنصة Discourse، وكل منها يتطلب عمقًا مختلفًا في الشرح. استخدم فئات التوثيق كدليل لتحديد الجمهور المستهدف لدليلك:

• Documentation > Using Discourse
• Documentation > Site Management
• Documentation > Integrations
• Documentation > Hosted Customers
• Documentation > Self-Hosting
• Documentation > Migrating to Discourse
• Documentation > Developer Guides
• Documentation > Contributing

افهم المستوى التقني لجمهورك المستهدف وقم بتكييف دليلك وفقًا لذلك. بعض النصائح:

• تجنّب الخطوات التي لا يستطيع الجمهور تنفيذها (على سبيل المثال، عملاء الاستضافة الموقّعة لا يملكون عمومًا وصولاً إلى أوامر وحدة التحكم)
• اجعل التعليمات واضحة وتجنّب اللغة التقنية المعقّدة للمستخدمين غير التقنيين
• لا تضيف معلومات خلفية يفترض أن يعرفها جمهورك بالفعل

الهيكل والأسلوب

يغطّي دليل أسلوب التوثيق كل ما تحتاج إلى معرفته حول كيفية هيكلة وتنسيق أدلة “كيف” (وجميع وثائق Discourse الأخرى):

Writing effective documentation for Discourse

Discourse documentation is currently being reviewed and edited to align with this style guide. Not all documentation topics currently match up to this - we are working toward that as quickly as possible. This is considered a living document that guides how Discourse documentation is written and formatted. This topic will be kept up to date as needed. If you are in doubt about any of the principles here, please post on the topic to discuss specifics. The guiding principl…

نشر دليل

انشر الأدلة في فئة فرعية من الفئة الرئيسية Documentation وعلّمها بـ how-to. تتطلب جميع الأدلة موافقة فريق Discourse، والتي ستتم معالجتها تلقائيًا عبر عملية الإشراف. يصف دليل الأسلوب كل فئة بتفصيل أكبر لمساعدتك في تحديد مكان نشر دليلك.

صيانة دليلك

بمجرد نشر دليل “كيف”، حافظ على تحديثه. إليك كيف يمكنك المساعدة في صيانته:

1. راقب الردود — دمج ملاحظات المجتمع في الدليل.
2. اختبر الدليل بنفسك — مرّ على الدليل دوريًا للتأكد من دقته.
3. عدّل المعلومات المفقودة أو غير الصحيحة — إذا كنت في مستوى الثقة 2 أو أعلى، عدّل المنشور الأول لدليل “كيف”.
4. علّم المواضيع للمساعدة — إذا لم تستطع إجراء تعديل، علّم المنشور بـ “شيء آخر” وشرِح ما هو مطلوب.

في معظم الحالات، سيتم حذف التعليقات على أدلة “كيف” الرسمية بعد شهر للحفاظ على التركيز على الدليل نفسه.

---

شكرًا لك على تحسين توثيق مجتمع Discourse! إذا واجهت صعوبة، فلا تتردد في طلب المساعدة. أفضل طريقة للبدء هي بالمشاركة والتعلّم أثناء التقدم.