يمكن إدارة كل خدمة تقدمها Selectel في حسابك الشخصي - لوحة التحكم . يمكن أيضًا التحكم في العديد من منتجاتنا عبر طلبات واجهة برمجة التطبيقات. تتوفر إرشادات المنتج ووثائق API في مركز مساعدة واحد .
تتمثل الفكرة الرئيسية لمركز المساعدة في تزويد عملائنا بفرصة العثور بشكل مستقل على إجابات لمعظم أسئلتهم حول خدمات Selectel في أي وقت يناسبهم.
بعد ذلك ، سنتحدث عن كيفية تغييرنا لنهج إعداد الوثائق وتحديث مظهر قاعدة المعرفة.
غطى التنفيذ الفني لقاعدة المعرفة ومكونها المرئي قبل ثلاث سنوات جميع احتياجات الكتاب المرجعي بالمعلومات. لكن خلال الوقت الماضي ، لم تقف الشركة مكتوفة الأيدي ، ولكنها كانت تتطور بنشاط ، من خلال إطلاق خدمات جديدة وتطوير الخدمات الحالية.
منذ حوالي عام ، لاحظنا أن المساعدة الموجودة عبر الإنترنت لا تلبي متطلبات عملائنا:
- نمت قائمة التنقل مثل شجرة الفاكهة التي لا تعرف رعاية بستاني ؛
- لم يعد البحث مريحًا ؛
- أصبح التصميم المرئي قديمًا بشكل تدريجي.
في السابق ، لم تكن وثائق واجهة برمجة التطبيقات الخاصة بمنتجاتنا متاحة للجمهور - تم نشر بعضها في لوحة التحكم my.selectel.ru ، وتم إصدار بعضها عند الطلب ، وتم وصف بعضها بالكامل بتنسيق نصي ، والذي تم تحديثه باستمرار إشكالية جدا. الآن معرفة أتمتة البنية التحتية لتكنولوجيا المعلومات والتفاعل مع الواجهة الخلفية لخدمات Selectel في علامة تبويب وثائق API .
رحلة صغيرة إلى الماضي
قبل عشرة أو خمسة عشر عامًا ، كان عدد قليل من الشركات المنتجة للبرامج في روسيا تفتخر بالحصول على مساعدة عبر الإنترنت. تمت كتابة أدلة التشغيل بتنسيق Word باستخدام أنماط دائمة الحركة ، في محاولة لتطبيق معايير GOST التي تم إنشاؤها في السبعينيات من القرن العشرين على المتطلبات الحديثة والمتغيرة باستمرار.
لا يزال الميم شائعًا بين الكتاب التقنيين:
حتى يومنا هذا ، هناك شركات يمكنها بالفعل التباهي بواجهة موقع سهلة الاستخدام ، لكن وثائقها تظل على مستوى "تعليمات التنزيل بتنسيق pdf لـ 45 ورقة".
في الشركات الكبيرة ، ترتبط قاعدة المعرفة بقوة بالدعم الفني. في عالم كروي مثالي في فراغ ، يجب أن يكون المستخدم قادرًا على العثور بشكل مستقل على 80٪ من إجابات أسئلتهم ، دون الاتصال بالدعم الفني.
لا تحقق البوابة الإلكترونية التي تحتوي على وثائق أي ربح واضح ، ولكن يمكنها توفير وقت الدعم الفني بسبب البرنامج النصي:
- طلب المستخدم الخدمة.
- في مواجهة لحظات غير واضحة عند الإعداد.
- كنت أرغب في الاتصال بالدعم الفني.
- ذهبت إلى قاعدة المعرفة ووجدت المعلومات التي احتاجها بنفسي.
- لم أتصل بالدعم الفني.
- الربح!)
غالبًا ما يكون هناك رأي مفاده أن معلومات المساعدة تساعد المستخدمين فقط على فهم الخدمات بعد اتصالهم. ربما كان هذا هو الحال في الأيام التي تم فيها نشر الكتب المطبوعة التي تحتوي على معلومات حول العمل في Windows. ولكن الآن أصبح من المهم بنفس القدر أن نوضح للمستخدمين المحتملين كيف تعمل الخدمة قبل الشراء.
تقوم معظم شركات البرمجيات بتطوير واجهات برمجة التطبيقات في مرحلة ما للاستخدام الداخلي والعملاء. تشترك الشركات في مجموعة من المدخلات من خلال إطلاق واجهات برمجة التطبيقات العامة لتمكين العملاء من دمج خدماتهم مع منتجات الشركة.
يمكن أتمتة العديد من المهام المخصصة ، بما في ذلك استخدام أجزاء جاهزة من التعليمات البرمجية كمُنشئ لإنشاء البنية التحتية الأكثر سهولة في الاستخدام. لكن أجزاء الكود بدون تفسيرات لما هو عليه ، وماذا يفعل وكيف تستخدمه ليست ذات فائدة تذكر - لن تضطر إلى معرفة الأساليب وما البيانات التي يتوقعونها للإدخال.
- ما الذي يجب فعله لجعل واجهة برمجة التطبيقات العامة ممتعة للاستخدام؟كوثيقة لواجهة برمجة التطبيقات ، عادةً ما يقدمون مثالًا بسيطًا على التفاعل ، والذي يصف الطرق (تسمى أيضًا نقاط النهاية) ويقدم استجابات من الخدمة. على سبيل المثال ، باستخدام Kubernetes API ، يمكنك أتمتة العمل مع المجموعات والعقد في Managed Kubernetes .
- إرفاق الوثائق!
ما هي المهام التي كانت تنتظرنا
توقف حلنا المرئي عن تسهيل العثور على المقالات التي نحتاجها ، وتحولت القائمة الحالية إلى "ورقة" غير قابلة للقراءة. التوثيق غير المقروء سيء مثل النصوص غير ذات الصلة. اعتاد الناس على قراءة المواد المعدة جيدًا. المدونات والشبكات الاجتماعية والوسائط - لا يتم تقديم كل المحتوى بشكل جميل فحسب ، بل يسهل أيضًا قراءته وإرضاء العين. حاليًا ، لا يمكن تجاهل متطلبات UX و UI ، خاصة لمثل هذه المجموعة الضخمة من النصوص.
مع تطور تقنيات التصميم المرئي للمواقع ، لاحظنا أن مظهر قاعدة المعرفة لدينا أصبح قديمًا. لم يساعد استخدام المراسي والقوائم في مقالات قاعدة المعارف. كان من الضروري مراجعة الهيكل الكامل للوثائق ومحرك البحث.
المشاكل الشائعة مع التوثيق
غائب بشكل عام أو لا يعلم أحد بوجوده ،
والتعليمات التي لا يمكن العثور عليها ليست أفضل من التعليمات غير الموجودة.
لقد حللنا هذه المشكلة بالطريقة التالية - بدأنا في إضافة روابط لمقالات مفيدة في قائمتنا البريدية الشهرية ، وإضافة انتقالات على صفحات المنتج بالموقع ، وكذلك إعداد إشعارات لجميع موظفي الشركة المهتمين من خلال قناة خاصة في برنامج مراسلة الشركة.
عفا عليها الزمن ولم يتم تحديثها في الوقت المناسب
عملية التوثيق ليست مضمنة في تطوير المنتج ، يتم التوثيق على أساس المتبقي.
في حالتنا ، يُكلف مدير المنتج أيضًا بتوثيق هذه الوظيفة الجديدة أثناء العمل على وظائف جديدة.
الوثائق معقدة وسيئة التنظيم ، ومن الأسهل أن تطلب من الدعم الفني كيفية حل المشكلة ،
كتابة الوثائق من أجل التوثيق لا طائل من ورائها ، يجب أن يكون الوصول إليها سهلاً. كلما زادت الخيارات للعثور على مستند ، كان ذلك أفضل.
قمنا بمراجعة تصميم أقسام قاعدة المعارف الخاصة بنا بالكامل ، وفي بعض الحالات لم تعمل القوالب العامة ، لذلك كان علينا التفاعل بنشاط مع جميع أصحاب المصلحة ، سواء كانوا مدير المنتج أو الدعم الفني أو فريق التطوير الأمامي.
نقل وثائق API إلى الفضاء العام
تتمثل إحدى تحديات استخدام وثائق API التي تم إنشاؤها في OpenAPI أو Swagger أو أداة جيل أخرى في التكامل المعقد مع بقية الموقع. من الضروري أن يكون لدى المستخدمين وصول سهل إلى جميع الإرشادات والمقالات - من غير الملائم أن يتم عرض نقاط النهاية في عرض واحد ، ويتم عرض أوصاف نصية لنفس العمليات في صفحة أخرى.
الحفاظ على صورة مرئية واحدة
عند إنشاء مركز مساعدة واحد ، احتجنا إلى الحفاظ على عرض متسق للإرشادات والمواصفات ، باستخدام مجموعة من "git + markdown + swagger".
كيف يعمل الآن
التنفيذ الفني
تم بناء قاعدة المعرفة في الأصل حول مزيج من Confluence ومولد صفحة ثابتة.
تخلينا عن التقاء وانتقلنا إلى التوثيق كرمز. الآن يتم كتابة جميع التعليمات البرمجية المصدر لقاعدة المعرفة بتنسيق Markdown ويتم تخزينها في نظام تخزين إصدار Git. يتم إنشاء موقع قاعدة المعرفة من المستودع باستخدام Hugo Static Site Generator.
يتم إنشاء الموقع من الملفات الموجودة في الفرع الرئيسي لمستودع Git. يمكن تحديث البيانات فقط من خلال طلب سحب ، مما يسمح لك بالتحقق من جميع الأقسام الجديدة من الوثائق قبل نشرها في المجال العام. يسهل مثل هذا النظام أيضًا نهج إجراء التعديلات - يمكن لموظفي الشركة دائمًا إنشاء فرع وإضافة جميع التغييرات اللازمة إليه.
المزيد عن التوثيق كرمز
مبدأ "التوثيق كرمز" يعني استخدام نفس الأدوات لكتابة الوثائق لإنشاء الكود:
- لغات ترميز النص ؛
- أنظمة التحكم في الإصدار
- مراجعة التعليمات البرمجية.
الهدف الرئيسي من هذا النهج هو تهيئة الظروف للفريق بأكمله للعمل معًا على النتيجة النهائية - قاعدة معرفية كاملة وإرشادات لاستخدام الخدمات الفردية للمنتج.
العمل مع ملفات التباهي
يقوم مطورو منتجات Selectel بإنشاء واجهة برمجة تطبيقات وتحميل التعليقات إلى الكود بتنسيق swagger - هذا ملف نصي بتنسيق * .yaml يمكن استخدامه كرمز. عندما يتم تحديث API ، يتم أيضًا تحديث ملف swagger ، مما يسهل تحديث الوثائق.
يتم استخدام الحل التقني التالي لوثائق API:
- مستودع git مع ملفات مواصفات swagger بتنسيق * .yaml ، مجمعة حسب المنتج ؛
- مستودع git مع ترجمة مواصفات swagger بتنسيق * .json ؛
- مستودع git بملفات بتنسيق * .md ؛
- تحتوي الملفات بتنسيق * .md على أوصاف نصية وملفوفة في علامات وصف نقطة نهاية خاصة يتم سحبها من مستودع git مع ملفات بتنسيق * .json ؛
- مولد موقع ثابت هوغو.
بالإضافة إلى هيكل المستودع ، تم تطوير قواعد للعمل معه:
- تم إعداد دليل نمط - قائمة مرجعية لملفات التباهي ، والتي يتحقق المطورون منها عند تحديث مواصفات واجهة برمجة التطبيقات ؛
- يعكس الفرع الرئيسي لمستودع git الذي يحتوي على ملفات بتنسيق * .md حالة المواصفات الحالية وهو في الواقع قيد الإنتاج ؛
- يتم تنفيذ طلب السحب إلى الفرع الرئيسي عند طرح التحديثات في الإنتاج.
المكون المرئي
كانت الخطوة الأولى هي مراجعة التنقل وإنشاء القواعد التي سيتم بموجبها تشكيل أقسام قاعدة المعرفة. بالتعاون مع مصممي UX ، قمنا بإعداد بنية معلومات. يجب أن يكون الهيكل شفافًا قدر الإمكان حتى لا يفكر القارئ: "أين يمكنك العثور على هذه المقالة؟" للتلخيص ، هناك طريقتان:
- من الواجهة. يكرر المحتوى أقسام اللوحة (بشكل منفصل للخدمات). كان هذا هو الحال في الإصدار السابق من قاعدة المعرفة.
- من المهام. تعكس عناوين المقالات والأقسام مهام المستخدمين.
من أجل تبسيط الهيكل ، استخدمنا مزيجًا من هذين النهجين. حتى في الإصدارات الأحدث من لوحة التحكم مع UX و UI مدروسين جيدًا ، من الضروري شرح المصطلحات على الأقل ، نظرًا لأن منتجاتنا معقدة تقنيًا والمستخدمون مختلفون تمامًا.
بالإضافة إلى تحديث جدول المحتويات ، قمنا بتحسين البحث وفتات التنقل. "فتات الخبز" هي مسار المستخدم إلى الصفحة الحالية مع إمكانية العودة إلى أي مستوى. في الإصدار السابق من قاعدة المعرفة ، كان من المستحيل الدخول إلى جدول المحتويات وكان ذلك غير مريح ، لذلك قمنا بإصلاحه في الإصدار الجديد.
تقوم كل شركة بعمل وثائق API وفقًا لرؤيتها الخاصة للأسلوب والبنية والشعور بالجمال. إذا فتحنا 4-5 واجهات برمجة تطبيقات عامة لشركات مختلفة ، فسنتمكن بلا شك من التعرف على بعض القواسم المشتركة: الهيكل ، وأمثلة الكود الضخمة ، وإبراز البنية ، والصفحات الطويلة. ومع ذلك ، سيكون لجميع الأمثلة ميزات خاصة. على سبيل المثال ، يعد توطين أوصاف نقطة النهاية أمرًا نادرًا ، بينما تبدو بنية أوصاف نقطة النهاية متشابهة في أغلب الأحيان.
عدة توصيات لهيكلة وثائق API:
تجميع نقاط النهاية
بالإضافة إلى توفير المعلومات لكل نقطة نهاية ، إذا كان هناك العديد من نقاط النهاية ، فمن المستحسن تجميعها. القائمة الطويلة المستمرة لنقاط النهاية تجعل التنقل صعبًا.
وصف منفصل للطرق
عند استخدام طرق GET / POST في نفس الوقت ، يجب وصف طريقة واحدة فقط في سطر واحد.
أي ، السطر الأول في هذه الحالة هو وصف GET ، والسطر الثاني هو وصف POST ، لذا يمكنك تجنب الالتباس.
أتمتة إجراء التغييرات
تبسيط إجراء التغييرات دون إعادة تهيئة كل قسم يدويًا - في حالتنا ، نقوم فقط بترجمة نص ملف swagger ، دون لمس الترميز بفضل أتمتة هذه العملية ، التي قام المتخصصون بتكوينها.
بناء الجملة يبرز
حب المطورين لأمثلة الكود أكثر في العالم ، ولن يشكو أي مطور من وجود العديد من الأمثلة - فهي تقلل إلى حد كبير من وقت الانغماس في المنتج.
يكون العمل مع أجزاء من التعليمات البرمجية أكثر ملاءمة عندما يتم تلوين العناصر المختلفة بشكل مناسب اعتمادًا على لغة البرمجة.
نظرًا لأن تمييز الكود الجاهز متاحًا فقط للخلفيات المظلمة ، فقد قام مطور الواجهة الأمامية بتعديل هذا الحل باستخدام high.js لأسلوب شركتنا.
بدلا من الاستنتاج
قاعدة المعرفة المحدثة متاحة للمستخدمين منذ مارس ، ووثائق API متاحة منذ أوائل أغسطس.
"- معنا ، عندما تركض لفترة طويلة ، ستجد نفسك بالتأكيد في مكان آخر.ما فعلناه بالفعل هو مجرد خطوة أخرى نحو تحسين قاعدة المعرفة. سنضيف تدريجيًا تعليمات ووثائق جديدة إلى واجهات برمجة التطبيقات لخدماتنا الأخرى.
"حسنًا ، هنا ، كما تعلم ، عليك الركض بأسرع ما يمكن للبقاء في نفس المكان ، وللوصول إلى مكان آخر ، عليك الركض بسرعة مضاعفة."
(لويس كارول "أليس عبر الزجاج")