يتم حالياً مراجعة وتحرير وثائق Discourse لتتوافق مع دليل الأسلوب هذا. لا تتطابق جميع موضوعات الوثائق الحالية مع هذا الدليل - نحن نعمل على تحقيق ذلك بأقصى سرعة ممكنة.
يُعتبر هذا المستند وثيقة حية تُوجّه كيفية كتابة وتنسيق وثائق Discourse. سيتم تحديث هذا الموضوع حسب الحاجة. إذا كنت متردداً بشأن أي من المبادئ المذكورة هنا، يرجى النشر في الموضوع لمناقشة التفاصيل.
المبدأ التوجيهي وراء دليل أسلوب هذه الوثائق هو مراعاة قراءك واحتياجاتهم عند كتابة الوثائق: ما الذي يريدون إنجازه؟ ما هو هدفك من تقديم المحتوى؟
قائمة تحقق سريعة عند تطبيق دليل الأسلوب:
- وجود كتلة التعريف (Meta block) وصحتها
- العنوان موجّه نحو الإجراء
- جميع العناوين تستخدم حالة الجملة (sentence case)
- استخدام الوسوم والفئات الصحيحة
- هيكلية المستند منطقية
عند إكمال مستند، راجعه للتأكد من استيفاء جميع هذه المعايير.
يرجى الانتباه إلى إرشادات تنسيق النص التالية:
معلومات التعريف (Meta information)
- يجب أن ينتمي المستند إلى فئة واحدة فقط من الفئات التالية:
- استخدام Discourse
- أدلة عامة للمستخدمين للمهام غير الإدارية
- إدارة الموقع
- الإعدادات، الإضافات، المحتوى، والإدارة العامة للموقع
- التكاملات
- أدلة لدمج منصات أخرى مع Discourse
- العملاء المستضافون
- أدلة ذات صلة فقط بالعملاء المستضافين
- الاستضافة الذاتية
- أدلة ذات صلة فقط بالمواقع المستضافة ذاتياً
- أدلة المطورين
- أدلة تقنية للتطوير فوق Discourse، بما في ذلك إنشاء السمات، مكونات السمات، والإضافات
- المساهمة
- أدلة للمساهمة في مشروع Discourse مفتوح المصدر
- استخدام Discourse
- يجب أن ينتمي المستند إلى وسم واحد فقط من أنواع المستندات/الوسوم التالية:
#how-to#explanation#reference#tutorial
- قد يحتوي المستند على أي وسوم أخرى ذات صلة، بحد أقصى مطلق هو 5 وسوم في مستند واحد
كتلة التعريف (Meta block)
يجب أن تحتوي جميع المستندات على كتلة في الأعلى تتضمن شرحاً مختصراً لموضوع المستند بالإضافة إلى أي معلومات تعريفية أخرى ذات صلة، مثل مستوى المستخدم المطلوب، أو ما إذا كان الوصول إلى وحدة التحكم (Console) مطلوباً، أو أي شيء آخر. سيتم تنسيق هذا في اقتباس (blockquote) دون عنوان فوقه. إليك مثالاً على الشكل المطلوب:
هذا دليل يصف جميع إعدادات الموقع المخفية المتاحة، وكيفية تمكينها، ولماذا قد ترغب في تعديلها.
مستوى المستخدم المطلوب: مدير
الوصول إلى وحدة التحكم مطلوب
العناوين والعناوين الفرعية
- اجعل عناوين المستندات موجّهة نحو الإجراء
- غير صحيح: “كيفية تمكين العناوين التلقائية لمواضيع الدردشة”
- صحيح: “تمكين العناوين التلقائية لمواضيع الدردشة”
- لا يجب أن تكون عناوين المستندات طويلة جداً
- لمواضيع “كيفية القيام بذلك” (how-to)، اجعل العنوان موجهاً نحو الهدف
- يجب أن تكون جميع العناوين محددة وفريدة
- لا تستخدم علامات الترقيم أو الأحرف الخاصة في عناوين المستندات، باستثناء الفواصل
- لا تتضمن رموز تعبيرية (emojis) في عناوين المستندات
- استخدم حالة الجملة (sentence case) للعناوين والعناوين الفرعية - وهذا يعني أن الكلمة الأولى فقط تبدأ بحرف كبير، بالإضافة إلى الأسماء الصحيحة وأي كلمات أخرى تُكتب عادة بحرف كبير
- لا تستخدم علامة & في العناوين، بل استخدم الكلمة الكاملة (“and”)
إرشادات الكتابة العامة، النبرة، والقواعد النحوية
- استخدم صوت الضمير الثاني (second-person) عند الإشارة إلى الأشخاص الذين يقرؤون المستند - أي استخدم “أنت”، وليس “نحن”
- استخدم الصيغة الفاعلة (active voice) قدر الإمكان
- غير صحيح: “يجب الضغط على الزر”
- صحيح: “اضغط على الزر”
- عرّف الاختصارات والاختصارات عند استخدامها لأول مرة، وإذا لزم الأمر، قدم رابطاً خارجياً يوفر المزيد من المعلومات
- استخدم جمل قصيرة، وقسّم النص باستخدام فقرات أقصر، وعناوين، وقوائم
- يمكنك استخدام
**عريض**و*مائل*لتسليط الضوء على عبارات أو كلمات رئيسية، لكن لا تفرط في استخدامها - تجنب استخدام المصطلحات التقنية أو المصطلحات المتخصصة دون شرح - إذا كنت متردداً، فاعتمد على الشرح
- استخدم لقطات الشاشة عند وصف واجهة مرئية، مثل عنصر واجهة مستخدم (UI)
- لا توثق أو تحاول الكشف عن ميزات أو منتجات أو خدمات Discourse المستقبلية ما لم يُسمح بذلك صراحة
- استخدم كلمات انتقالية مثل لذلك، على الرغم من، وعلاوة على ذلك.
- استخدم الاختصارات الشائعة: إنها، ستفعل، أنت، نحن، دعنا
- استنتج الخلود في الوثائق - تجنب كلمات مثل قريباً، جديد، الآن، الأحدث، وما إلى ذلك التي تصبح غير ذات صلة بسرعة
- لا تُنسب الصفات البشرية إلى البرامج أو الأجهزة
- مثال: “إذا مررت عدداً صحيحاً إلى هذه الواجهة البرمجية، فسوف تغضب وترفع خطأً”
- مثال: “روبوتنا الذكي الودود والطموح سيساعد في حل جميع مشاكلك”
- عند اقتباس نص (بما في ذلك من واجهة مستخدم Discourse)، استخدم “علامات الاقتباس”
- عند اقتباس عنوان URL، استخدم
أقواس خلفية - عند استخدام نطاق مثال، استخدم
discourse.example.com - إذا كان ذلك مفيداً، يمكنك استخدام الرموز التعبيرية (emojis) في بداية الفقرة لتسليط الضوء عليها. لا تستخدم أكثر من اثنين أو ثلاثة منها في موضوع واحد. إليك بعض الأمثلة على الرموز التعبيرية التي يمكنك استخدامها:
- - ملاحظة معلوماتية
- إعلان أو إشعار
- رسالة تحذير
- معلومات مهمة جداً
- تجنب:
- الاستعارات أو الفكاهة غير الضرورية
- المراجع الثقافية والإقليمية
- فرض أوامر الإجراءات بنبرة متعالية - مثل يجب عليك الضغط على نشر أو تحتاج إلى الضغط على نشر
- أن تكون مهذباً بشكل مفرط. على سبيل المثال، يرجى الضغط على نشر
- استخدام علامات التعجب إلا عند الضرورة القصوى
- كتابة الكلمات بحروف كبيرة حيث لا داعي لذلك
- الإفراط في استخدام العبارات والضمائر نفسها
لوثائق المستخدم النهائي:
حافظ على نبرة ودية وغير رسمية، مع التركيز على الوضوح والإيجاز بطريقة وافية. اذهب إلى النقطة بسرعة. اشرح المصطلحات التقنية، لكن احذر من أن تكون متعجرفاً. لضمان الوضوح، ابدأ بتحديد سياق الموضوع الحالي باختصار.
لوثائق المطورين والوثائق التقنية:
حافظ على نبرة مباشرة ودقيقة. استخدم نفس النبرة التي تستخدمها لوثائق المستخدم، لكن يمكنك افتراض مستوى أعلى من المعرفة التقنية لدى قرائك.
الهيكلية
- اذهب إلى النقطة بسرعة - ابدأ بأهم شيء
- أضف الكلمات المفتاحية المهمة في بداية المستند
- اجعل خيارات القارئ والخطوات التالية واضحة
- استخدم دائماً تنسيقاً خفيفاً (light markup) لكتابة الوثائق (تم دمج هذا بالفعل في Discourse مع Markdown-it).
- مرجع الاستخدام: https://markdown-it.github.io/
- نظّم وثائقك بتسلسل منطقي - ابدأ بنظرة عامة، تليها أقسام مفصلة، ثم ملخص أو خاتمة إذا لزم الأمر
- استخدم العناوين والعناوين الفرعية لتنظيم محتواك، مما يسهل على القراء التصفح والعثور على معلومات محددة - استخدم تسلسلاً هرمياً تنازلياً في العناوين، بدءاً من h2، ولا تتخطى المستويات
- قدم روابط لمواضيع أو أقسام ذات صلة داخل وثائقك - هذا يساعد المستخدمين على العثور على معلومات إضافية دون عمليات بحث غير ضرورية
الروابط
- استخدم نصاً ذا معنى في الروابط
- ما لم يكن تنسيق عنوان URL مهماً أو توضيحياً، لا تستخدم عنوان URL كنص للرابط - بدلاً من ذلك، استخدم عنوان الصفحة أو وصفاً للصفحة
- اربط بالمواقع والمصادر الخارجية بدلاً من اقتباس أو إعادة كتابة الوثائق الموجودة
- تأكد من أن المواقع التي تربط بها ذات جودة عالية
- إذا كان الرابط يقوم بتنزيل ملف، اذكر ذلك صراحة - كما حدد نوع الملف الذي يتم تنزيله وتقديراً تقريبيًا لحجم الملف
الكود في الوثائق
- استخدم كتل الكود مع تمييز بناء الجملة الخاص باللغة عند الإمكان لأمثلة الكود الكبيرة
- إذا لم يكن المثال واضحاً بذاته، قدمه بجملة تمهيدية تثير المثال التالي - إذا كنت متردداً، فاعتمد على الشرح
- يجب أن تتبع أمثلة الكود أفضل الممارسات لكتابة الكود للغة البرمجة ذات الصلة
- استخدم كوداً مضمنًا (inline code) للتعبير عن سمات الكود الأساسية أو عندما لا تكون كتلة كود كاملة ضرورية، مثل:
- أسماء وقيم السمات
- أسماء الفئات
- أسماء أدوات سطر الأوامر
- أنواع البيانات
- أسماء متغيرات البيئة
- أسماء الملفات، امتدادات الملفات، والمسارات
- المجلدات والدلائل
- أفعال HTTP، أكواد الحالة، وقيم نوع المحتوى
- أسماء وقيم معاملات الاستعلام
- إدخال النص
- عند استخدام نموذج نائبة في أمثلة الكود، أو الأوامر، أو نصوص أخرى، قم بتضمين شرح لما تمثله النائبة
- اكتب شرحاً لأول مرة تستخدم فيها النائبة؛ إذا كانت هناك نائبات متعددة أو خطوات بعد الاستخدام الأول لتلك النائبة، يمكنك شرح النائبة مرة أخرى
- وفّر طريقة سهلة للمستخدمين أو المطورين لنسخ الكود وتشغيله.
- اعرض الناتج المتوقع، إما في قسم منفصل بعد مثال الكود أو باستخدام تعليقات الكود داخل مثال الكود
- اكتب كوداً آمناً - لا تقم أبداً بتشفير كلمات المرور، مفاتيح واجهة برمجة التطبيقات (API Keys)، أو المعلومات الآمنة في الكود
الإجراءات والأدلة خطوة بخطوة
- صغ الإجراءات بشكل متناسق، بحيث يمكن للقراء العثور عليها بسهولة عن طريق التصفح
- استخدم إدخالاً رقمياً منفصلاً لكل خطوة
- أضف الإجراءات التي تُنهي خطوة، مثل أزرار “موافق” أو “تطبيق”
- إذا ظهرت التعليمات في نفس واجهة المستخدم حيث يحدث الإجراء، فعادة لا يكون من الضروري تقديم تفاصيل الموقع
- إذا كنت بحاجة إلى التأكد من أن القارئ يبدأ من المكان الصحيح، قدم عبارة مختصرة في بداية الخطوة
إمكانية الوصول والشمولية
- استخدم لقطات الشاشة، المخططات، أو الفيديوهات حيث تضيف قيمة، خاصة لشرح خطوات معقدة أو إظهار أجزاء من واجهة المستخدم
- يجب استخدام الصور لدعم معلومات النص، وليس لاستبدالها
- استخدم دائماً سمات
altللصور - قدم دائماً تسميات توضيحية أو نصوصاً منقولة للفيديوهات
- استخدم صور GIF فقط إذا كنت تستطيع شرح المحتوى بالكامل في النص
- اختر صوراً بسيطة وقصّ التفاصيل الزائدة
- استخدم لغة بسيطة وتجنب المجازات أو التعابير التي قد لا تكون مفهومة عالمياً
- ضع في اعتبارك أن مستندك سيتم استخدامه على مجموعة متنوعة من الأجهزة
- استخدم لغة محايدة جنسانياً. لا تستخدم هو، له، منه، هي، لها، منها عند الإشارة إلى الأشخاص - للكتابة حول الضمائر، يمكنك:
- إعادة الصياغة باستخدام الضمير الثاني (أنت)
- إعادة صياغة الجملة لتصبح ذات اسم جمع وضمير جمع
- استخدام كلمات شخص أو فرد
- استخدام أدوات النكرة الـ، أ، أو بدلاً من الضمير
- استخدام ضمير جمع مثل هم، لهم، أو، حتى لو كان يشير إلى فرد واحد
- عندما تكتب عن شخص حقيقي، استخدم الضمائر التي يفضلها ذلك الشخص
- كن شاملاً للهوية الجندرية، العرق، الثقافة، الدين، القدرة، العمر، التوجه الجنسي، والطبقة الاجتماعية - أضف مجموعة واسعة من المهن، الثقافات، البيئات التعليمية، المناطق، والبيئات الاقتصادية في الأمثلة
- تجنب المحتوى السياسي - في الحالات التي يجب فيها تضمين محتوى سياسي، حافظ على الحياد
- لا تصدر أي تعميمات حول الأشخاص، الدول، والثقافات، حتى لو كانت تعميمات إيجابية أو محايدة
- لا تكتب محتوى متحيزاً أو تمييزياً ضد أي مجتمعات، خاصة الأقليات
- تجنب المصطلحات النوعية المتعلقة بالأحداث التاريخية
- تجنب استخدام المصطلحات والاستعارات المرتبطة بالعنف والعمليات العسكرية
.
). نقطة جيدة حول عدم الاتساق على الرغم من ذلك. لست متأكدًا من أي وثيقة سنستقر عليها، لكننا بالتأكيد سنتأكد من اختيار واحدة والالتزام بها. 