البرنامج التعليمي السابق: Developing Discourse Plugins - Part 6 - Add acceptance tests
لقد أنشأت الإضافة الخاصة بك، و رفعتها إلى GitHub، و أضفت اختبارات. ممتاز! المشكلة هي أنه لا أحد يعرف عنها.
توثيق الإضافة الخاصة بك
تتطلب جميع الإضافات توثيقًا جيدًا. يحتاج المستخدمون إلى معرفة ما تفعله الإضافة، وكيفية تثبيتها، والإعدادات/تغييرات التكوين الهامة المطلوبة، وكيفية استخدامها. يجب توثيق الإضافات في مكانين مختلفين: ملف README.md داخل مستودع Git الخاص بك، وموضوع مخصص في فئة Plugin.
توثيق GitHub
يعد ملف README.md على GitHub مهمًا لأنه يتم عرضه بشكل افتراضي عندما يزور المستخدم المستودع الخاص بك. كحد أدنى، يجب أن يتضمن ملف القراءة الخاص بك عنوان الإضافة ووصفًا موجزًا. سيتضمن ملف القراءة الأكثر اكتمالًا أيضًا تعليمات التثبيت، ووصفًا أكثر تفصيلاً، وتعليمات الاستخدام الأساسية، والترخيص، و (إذا كان ذلك منطبقًا) لقطات شاشة. إذا تم تضمين تعليمات إضافية في موضوع 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، حيث يمتلك كل مؤلف إضافة أسلوب التوثيق الخاص به. مهما كان الأسلوب الذي تختاره، تأكد من أنه واضح وسهل القراءة ومنظم. استخدم العناوين حسب الاقتضاء، وقم بشرح لقطات الشاشة لشرح التفاعلات المعقدة، وتأكد من الاتساق في التنسيق. تجنب إغراء كتابة فقرة واحدة عملاقة.
تحديث التوثيق الخاص بك
بعد كتابة التوثيق الأولي الخاص بك، من المهم الحفاظ عليه محدثًا.
هل أضفت ميزة جديدة إلى الإضافة؟ تأكد من تخصيص بعض الوقت لتوثيقها.
هل أجبت على نفس السؤال عدة مرات؟ فكر في إضافة قسم للأسئلة الشائعة إلى موضوع Meta الخاص بك.
هل هناك مشكلة معروفة يصعب إصلاحها؟ قم بتفصيلها في موضوعك حتى يعرف المستخدمون ما يمكن توقعه.
دعم الإضافة الخاصة بك
بعد نشر إضافتك وتوثيقها، قد يقوم مسؤولو الموقع الذين يجدونها مفيدة بتثبيتها على مواقعهم والبدء في استخدامها. يتطلب هذا الاستخدام دعمًا مستمرًا من مطور الإضافة. ستحتاج إلى الإجابة على الأسئلة التي يطرحها مسؤولو الموقع، ومساعدتهم في استخدام إضافتك. قد يكون الشيء الذي كان منطقيًا تمامًا بالنسبة لك غير واضح للآخرين، لذا ستحتاج إلى تحديث الكود و/أو التوثيق لتوضيحه. قد تتلقى طلبات ميزات، والتي سيتعين عليك أن تقرر ما إذا كنت ستضيفها أم لا.
أخيرًا، تخضع Discourse نفسها لتطوير مستمر. في حين أن إضافتك قد تعمل بشكل مثالي اليوم، فقد يتغير شيء غدًا يكسرها. تأكد من البقاء على اطلاع دائم بتطوير Discourse حتى تتمكن من تحديث إضافتك لدعم أحدث إصدار من Discourse عندما يؤثر تغيير ما على إضافتك.
المزيد في السلسلة
الجزء 1: أساسيات الإضافة
الجزء 2: منافذ الإضافة
الجزء 3: إعدادات الموقع
الجزء 4: إعداد Git
الجزء 5: واجهات المسؤول
الجزء 6: اختبارات القبول
الجزء 7: هذا الموضوع
يتم التحكم في إصدار هذه الوثيقة - اقترح تغييرات على github.
