استخدام النموذج الأولي كمواصفات منتج API

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

لقد تعلمت أن وثيقة متطلبات المنتج المتجانسة (PRD) هي طريقة أقل من مثالية للقيام بذلك وأن الواجهة القابلة للاختبار بما في ذلك نفس المعلومات مثل مواصفات المنتج ستكون بديلاً قويًا. تكمن مشكلة PRDs في أنها غالبًا ما تكون كبيرة جدًا ومعظمها نصوص. من السهل جدًا أن تفقد مكانك أو تفوت شيئًا مهمًا حقًا.

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

تحديد المتطلبات

كيف يجب أن تبدو هذه الواجهة القابلة للاختبار كمواصفات منتج؟ كيف ستعمل؟ هل تتواجد؟

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

متطلبات كاجان *:

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

قائمة أمنيات كاجان *:

• ستحتاج إلى استكمال النموذج الأولي [بـ]:
  • منطق الأعمال
  • متطلبات الإصدار
  • متطلبات تسليم المنصة
  • استخدم حالات
• أريد حقًا أن أكون قادرًا على إضافة تعليق توضيحي للنموذج الأولي

متطلباتي للنموذج الأولي حسب المواصفات:

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

إدخال StopLight

الأداة التي كنت أستخدمها والتي ترضي كل شيء تقريبًا تسمى Stoplight.io . إنه في جوهره محرك توثيق API ووكيل ويب. يسمح لك بتعريف API الخاص بك باستخدام واجهة مستخدم بديهية ، والتي لديها أفضل ما في Swagger و RAML خلف الكواليس كمحرك المواصفات الخاص بها إلى جانب القدرة على الاستيراد أو التصدير من أيٍّ من التنسيقين.

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

يحتوي وكيل StopLight أيضًا على العديد من الميزات المذهلة تمامًا:

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

إذا قارنت مجموعة قائمة أمنياتي ومتطلبات مواصفات Cagan وقائمة أمنياته بالوظيفة التي يوفرها StopLight ، يمكنك أن ترى أن StopLight يلبي كل حاجة ورغبة:

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

سير العمل في StopLight بسيط ويمكن لأي شخص القيام به ، بغض النظر عن قدراته الفنية:

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

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

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

* متطلبات Cagan وقائمة الرغبات هي اقتباسات مباشرة من Inspired: How to Build Products التي يحبها العملاء.