توثيق مكونات و ثيمات WordPress

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

لماذا التوثيق مهم؟

يعد الاحتفاظ بمجموعة محدثة من الوثائق حول مشاريعك أو أصولك أو منتجاتك أمرًا مهمًا لأسباب عديدة.

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

ثانيًا ، يعد الاحتفاظ بأصولك موثقة مفيدًا لمطوري WordPress الآخرين. وهذا منطقي حتى لو كنت مستقلاً منفردًا (أنت ملزم بالتعاون مع أشخاص آخرين في وقت ما). سيحتاجون إما إلى استخدام هذه الأصول أو سيُطلب منهم صيانتها و / أو تحديثها. إنه لأمر محبط للغاية الاضطرار إلى استخدام رمز غير موثق كتبه شخص آخر ، ليس موجودًا لتقديم الدعم أو شرح بعض الأجزاء الصعبة.

أخيرًا ، تضيف الوثائق أن المظهر "المصقول" لمنتجاتك وسيحبك عملاؤك أكثر.

5 مبادئ للتوثيق الفعال

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

دعنا ننتقل إلى أهم 5 حتى تتمكن من كتابة وثائق فعالة لمنتجاتك!

• يفضل استخدام كلمات أقل مما قد تستخدمه عادةً في كتابتك: يجب أن يكون لكل كلمة هدف. كن مباشرًا وبسيطًا. يُطلب التوثيق عادةً عندما يكون الشخص في مأزق ويريد إيجاد حل سريعًا. على سبيل المثال ، جملة مثل "الفشل في إتلاف الكائن Q سيؤدي إلى حدوث تسرب للذاكرة" أفضل من جملة "الفشل في إتلاف الكائن Q سيؤدي إلى حدوث تسرب للذاكرة".
• تفضل استخدام الصوت النشط بدلاً من المبني للمجهول: " انقر فوق الزر الموجود أعلى اليمين" بدلاً من " يجب النقر فوق الزر الموجود في أعلى اليمين". يزيل استخدام الصوت النشط أي غموض بشأن من يفعل ماذا. يتم استخدام الصوت المبني للمجهول فقط عندما تحتاج إلى التركيز على الكائن ، بدلاً من التركيز على الموضوع (على سبيل المثال ، تم تصميم منصة Pressidium مع وضع الأمان في الاعتبار ) .
• استخدم لغة وصفية عندما تحتاج إلى وصف المفاهيم ، والضرورة عندما تحتاج إلى وصف إجراء خطوة بخطوة (مثل البرامج التعليمية).
• استخدم قوائم النقاط عندما تحتاج إلى سرد الأشياء التي ليس لها ترتيب ، والقوائم المرقمة عندما يكون ترتيب النقاط مهمًا.
• تأكد من اختبار التعليمات بنفسك قبل تقديمها!

توثيق ملحقات WordPress

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

استضافة موقع الويب الخاص بك مع Pressidium

ضمان استرداد الأموال لمدة 60 يومًا

اطلع على خططنا

سيوفر لك نشر مكون WordPress الإضافي على wordpress.org مكانًا لوضع إرشادات التثبيت ولقطات الشاشة والأسئلة الشائعة حتى سجل التغيير! يعد ملئها بمعلومات مفيدة وعالية الجودة أمرًا أساسيًا في جعل المكون الإضافي الخاص بك أكثر شيوعًا:

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

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

توثيق قوالب ووردبريس

يعد توثيق سمات WordPress أمرًا مختلفًا تمامًا. المشكلة الأكثر شيوعًا في سمات WordPress هي عدم معرفة القسم الذي يتوافق مع العنصر المرئي. لا يتقن الجميع CSS:

• قم بإنشاء تسلسل هرمي لجميع أقسام CSS ، مع الأوصاف المقابلة.
• لكل قسم ، أضف لقطة شاشة توضيحية توضح بالتفصيل كل وظيفة ، جنبًا إلى جنب مع مثال صغير. لا تنس استخدام الصوت النشط واللغة الحتمية ، عند إظهار كيفية القيام بشيء يتطلب من المستخدم اتباع التعليمات.
• استخدم أداة مثل css_doc لمساعدتك. يؤدي هذا إلى إنشاء أسلوب JavaDoc من التوثيق ويمكن نشره.
• أحيانًا لا تكفي تعليقات الكود وتحتاج إلى إنشاء مستند دليل نمط لموضوع CSS الخاص بك. تصف وثائق دليل النمط كيف يجب أن تبدو العناصر وفي أي الحالات يجب استخدامها. إنهم يفرضون الاتساق ويجعلون التعاون أسهل أيضًا. انظر هذا المثال من قبل جوجل.
• استخدم إطار عمل CSS مثل Blueprint CSS. سيساعدك هذا في التطوير من خلال تزويدك بمجموعة من الأدوات مثل شبكة قابلة للتخصيص والطباعة الافتراضية التي تعمل وإعادة تعيين CSS للمتصفح وغير ذلك الكثير.
• مرة أخرى ، لا تنس الرجوع إلى معايير الترميز الرسمية لـ WordPress CSS.