الدرس السابق: Developing Discourse Plugins - Part 6 - Add acceptance tests
لقد أنشأت إضافتك، ورفعتها إلى GitHub، وأضفت الاختبارات. رائع! المشكلة هي أن لا أحد آخر يعرف عنها.
توثيق إضافتك
تتطلب جميع الإضافات توثيقاً جيداً. يحتاج المستخدمون إلى معرفة ما تفعله الإضافة، وكيفية تثبيتها، والإعدادات/التغييرات التكوينية المهمة المطلوبة، وكيفية استخدامها. يجب توثيق الإضافات في موقعين مختلفين: ملف README.md داخل مستودع git الخاص بك، وموضوع مخصص في فئة Customization > Plugin.
التوثيق على GitHub
يُعد ملف README.md على GitHub مهماً لأنه يظهر افتراضياً عند زيارة المستخدم لمستودعك. كحد أدنى، يجب أن يتضمن ملف readme عنوان الإضافة ووصفاً مختصراً. سيتضمن ملف readme الأكثر اكتمالاً أيضاً تعليمات التثبيت، ووصفاً أكثر تفصيلاً، وتعليمات الاستخدام الأساسية، والترخيص، و(إن لزم الأمر) لقطات شاشة. إذا كانت هناك تعليمات إضافية متضمنة في موضوع Meta الخاص بإضافتك، تأكد من تضمين رابط للموضوع.
مثال على إضافة موثقة بشكل أساسي: Discourse Data Explorer
أمثلة على إضافات ذات توثيق أكثر اكتمالاً: Discourse Solved، وDiscourse OAuth2 Basic، وDiscourse Ads.
نموذج README لإضافة تجريبية
تأكد من تحديث النص المحاط بـ <> بتفاصيل إضافتك الخاصة.
## <عنوان الإضافة>
<وصف الإضافة>
## التثبيت
اتبع [دليل تثبيت الإضافات](https://meta.discourse.org/t/install-a-plugin/19157).
## كيفية الاستخدام
<اشرح كيفية تفعيل الإضافة، خطوات التكوين الضرورية، وكيفية استخدامها>
## لقطات شاشة
<تضمّن لقطات شاشة إذا لزم الأمر لتوضيح استخدام إضافتك>
## اقرأ المزيد
<تضمّن رابطاً إلى موضوع Meta الخاص بك إذا كانت هناك معلومات مفصلة هناك>
## الترخيص
<اذكر ترخيص الكود الخاص بك، معظم إضافات Discourse تستخدم ترخيص MIT>
التوثيق على Meta
بينما يميل التوثيق على GitHub إلى أن يكون مختصراً وموجهاً “لنقطة الموضوع”، فإن التوثيق على Meta هو المكان الذي يمكنك فيه مشاركة كافة التفاصيل الكاملة لإضافتك، وإقناع المستخدمين بضرورة استخدامها. كحد أدنى، يجب أن يتضمن موضوع Meta الخاص بك وصفاً مختصراً للإضافة، ورابطاً إلى مستودع الإضافة على GitHub (ليتمكن المستخدمون من تثبيتها). سيتضمن التوثيق الأكثر اكتمالاً أيضاً وصفاً مفصلاً يتضمن حالات استخدام أمثلة، وتعليمات استخدام مفصلة، وتوثيقاً لكافة الإعدادات وخيارات التكوين، ولقطات شاشة. تُعد لقطات الشاشة أمرًا أساسياً لأن المستخدمين يريدون رؤية ما تفعله إضافتك، وليس مجرد القراءة عنها. قد تحتاج إضافة مزودة لموفر مصادقة إلى لقطة شاشة واحدة فقط، في حين يجب أن تحتوي الإضافة التي تضيف واجهة جديدة، أو تجري تغييرات رئيسية على عدد لا بأس به من اللقطات.
يميل التوثيق على Meta إلى أن يكون أكثر شخصية من GitHub، حيث يمتلك كل مؤلف إضافات أسلوب توثيق خاص به. بغض النظر عن الأسلوب الذي تختاره، تأكد من أنه واضح، وسهل القراءة، ومنظم. استخدم العناوين المناسبة، وعلّق على لقطات الشاشة لشرح التفاعلات المعقدة، وتأكد من الالتزام بالتنسيق بشكل متناسق. تجنب مغرية كتابة فقرة واحدة عملاقة.
تحديث التوثيق الخاص بك
بعد كتابة التوثيق الأولي، من المهم إبقاؤه محدّثاً.
أضفت ميزة جديدة إلى الإضافة؟ تأكد من تخصيص بعض الوقت لتوثيقها.
أجبت على نفس السؤال عدة مرات؟ فكّر في إضافة قسم الأسئلة الشائعة (FAQ) إلى موضوع Meta الخاص بك.
مشكلة معروفة يصعب إصلاحها؟ اشرحها في موضوعك حتى يعرف المستخدمون ما يمكن توقعه.
دعم إضافتك
بعد نشر إضافتك وتوثيقها، قد يقوم مسؤولو الموقع الذين يجدونها مفيدة بتثبيتها على موقعهم والبدء في استخدامها. يتطلب هذا الاستخدام دعمًا مستمرًا من مطور الإضافة. ستحتاج إلى الإجابة على أسئلة مسؤولي الموقع، ومساعدتهم في استخدام إضافتك. قد يكون شيئاً ما واضحاً تماماً لك غير واضح للآخرين، لذلك ستحتاج إلى تحديث الكود و/أو التوثيق لتوضيحه. قد تتلقى طلبات لميزات جديدة، والتي سيتعين عليك تحديد ما إذا كنت ستضيفها أم لا.
أخيراً، يخضع Discourse نفسه للتطوير المستمر. في حين أن إضافتك قد تعمل بشكل مثالي اليوم، قد يتغير شيء ما غداً يؤدي إلى تعطلها. تأكد من مواكبة تطورات Discourse حتى تتمكن من تحديث إضافتك لدعم أحدث إصدار من Discourse عند حدوث تغيير يؤثر على إضافتك.
المزيد في هذه السلسلة
الجزء 1: أساسيات الإضافات
الجزء 2: مخارج الإضافات
الجزء 3: إعدادات الموقع
الجزء 4: إعداد git
الجزء 5: واجهات المسؤول
الجزء 6: اختبارات القبول
الجزء 7: هذا الموضوع
هذا المستند خاضع لإدارة الإصدارات - اقترح التغييرات على github.
