وثائق المنتج لمتخصصي WordPress

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

لكن هذا تغير:

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

لماذا يجب أن يهتم محترفو WordPress بتوثيق المنتج؟

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

إذا كنت تعمل في وكالة WordPress ، فإن تقديم الوثائق عبر جميع مجالات المشروع ، من التصميم الأولي إلى الأصول ، سيضيف مستوى من الاحتراف يظهر ما يلي:

1. أنت تهتم بالتفاصيل.
2. أنت تهتم بعميلك بما يكفي لتذهب إلى أبعد من ذلك.
3. تتمتع بالشفافية والثقة في قراراتك المتعلقة بالتصميم والمشاريع الفنية.

كتب مايك بوتربو ، نائب الرئيس للتسويق في MindTouch مقالاً على موقع Mashable يصف فيه الأسباب الخمسة التي تجعل توثيق منتجك أحد الأصول التسويقية. وختم بما يلي:

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

الآن بعد أن أنشأنا الدافع الكافي ، سنقوم بما يلي:

1. استكشف الأنواع المختلفة لوثائق المنتج ذات الصلة بـ WordPress.
2. ناقش احتياجات كل نوع من الوثائق وقدم نصائح عملية.
3. قدم بعض الإرشادات الأولية حول كيفية التخطيط والتعاون في توثيق المنتج. خاصة إذا كنت تعمل في وكالة WordPress.

أنواع وثائق منتج WordPress

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

إضافات ووردبريس

تحتاج وثائق البرنامج المساعد لـ WordPress إلى تلبية احتياجات مجموعتين: المستخدمين والمطورين. تختلف احتياجات التوثيق لكل منها ، وكذلك أسلوب الكتابة المستخدم.

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

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

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

المستخدمون

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

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

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

المطورين

إلى جانب اتباع أفضل ممارسات البرامج ومعايير ترميز PHP الرسمية ، يجب أن تركز انتباهك على المجالات التالية:

خطاف البرنامج المساعد

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

علامات القالب

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

والخيارات

الخيارات هي طريقة لتخزين أجزاء معينة من المعلومات في قاعدة بيانات WordPress. يتم ذلك عبر الوظيفتين add_option و get_options. في هذه الحالة ، قم بتوثيق المعلمات التي تقوم بتمريرها إلى هذه الوظائف.

قاعدة البيانات

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

ثيمات WordPress

هناك مجالان مختلفان يمكنك إنشاء وثائق للسمات. الأول هو ملفات المصدر. ملفات CSS التي تم التعليق عليها أسهل في الفهم والقراءة من تلك التي لا تحتوي عليها. استخدم أداة مثل css_doc لمساعدتك. يؤدي هذا إلى إنشاء أسلوب JavaDoc من التوثيق ويمكن نشره:

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

مرة أخرى ، لا تنس الرجوع إلى معايير الترميز الرسمية لـ WordPress CSS.

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

مساعدة على الانترنت

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

يقدم Barry J. Rosenberg ، مؤلف كتاب Spring into Technical Writing ، النصائح التالية من أجل كتابة ملفات مساعدة جيدة:

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

محتوى دقيق

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

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

REST API

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

توثيق التعاون والتخطيط

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

1. سجل كل ما يريد المستخدم معرفته ، بالإضافة إلى المجالات التي ستحتاج لكتابة نص لها.
2. بمجرد حصولك على كل شيء ، قم بتجميعها في فئات وعناوين مستندات النموذج.
3. اكتب مواصفات لكل مستند توضح بالتفصيل أشياء مثل العنوان ، والوصف ، والجمهور المستهدف ، والوسائط (ما هو شكل المستند) ، والطول ، وكم من الوقت سيستغرق ، وما إلى ذلك.
4. أضف التقديرات من مواصفات الوثائق إلى تخطيط مشروعك.

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

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

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

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

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

إغلاق

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