لماذا تعاني من التوثيق؟ أنشئ وثائق منتجات جذابة بدون مهارات برمجية

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

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

عند بناء وثائق المنتج، تستخدم الفرق عادةً أدوات توثيق جاهزة مثل Notion، أو أدوات إدارة المحتوى مثل Confluence و CMS، أو مولدات الوثائق مثل Docusaurus و Gitbook. ومع ذلك، غالبًا ما تواجه هذه الحلول المشكلات التالية:

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

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

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

الخلفية

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

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

العملية الأساسية

1. إنشاء فرع سباق (Sprint Branch) لإدارة المحتوى والتعاون

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

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

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

2. استخدام محرر Markdown الجميل لكتابة كل وثيقة

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

بالإضافة إلى الإدراج البصري لنمط MD العام، أضاف Apidog الميزات الخاصة التالية:

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

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

3. تعاون زملاء المنتج/العمليات لتنقيح الوثائق

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

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

الآن باستخدام Apidog، يمكن للطرفين إجراء تعديلات مباشرة في الوثائق، مع إشعارات رسائل فورية تُرسل إلى برامج المراسلة الفورية (IM) عند إجراء التغييرات، مما يسمح للآخرين بالدخول فورًا إلى الوثيقة ورؤية التغييرات المحددة بسهولة، مما يحسن كفاءة التعاون بشكل كبير. فيما يلي الخطوات المحددة:

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

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

4. التحضير والمراجعة قبل النشر الرسمي للوثيقة

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

يقوم فريق العمليات بتأكيد وثائق المحتوى المكتملة من هذا التكرار، ويحددونها، ويقدمون طلب دمج (MR) لدمجها في الفرع الرئيسي.

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

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

مزايا أخرى

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

1. تعيين أنماط موقع الوثائق الشاملة التي تتطابق مع نمط المنتج/الشركة

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

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

2. تجربة نشر بدون صيانة

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

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

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

3. إعدادات متعددة صديقة لتحسين محركات البحث (SEO)

يقوم Apidog تلقائيًا بإنشاء عناوين URL (Slugs) معقولة لمواقع الوثائق المنشورة بناءً على الإعدادات الأساسية للسماح للمستخدمين بالوصول إليها ومشاركتها بشكل أفضل.

بالطبع، إذا كانت لديك احتياجات متقدمة لتحسين محركات البحث (SEO)، فإنه يدعم أيضًا عناوين URL مخصصة (Slug)، والبيانات الوصفية (Meta Data)، وإعدادات المحتوى المتنوعة الأخرى لكل وثيقة على حدة.

الخاتمة

ما سبق هو الممارسة المحددة لاستخدام Apidog لصيانة وثائق المنتج.

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