مشكلة مفاتيح API التي لا تنتهي صلاحيتها أبدًا
المفتاح الذي صدر قبل سنوات، ولم يُبدَّل قط، ولا يزال صالحًا حتى اليوم ليس ميزة مريحة. إنه عبء لم ينظر فيه أحد فعلًا منذ سنوات.
لماذا تهم جودة التوثيق أكثر من عدد الميزات
صفحة أسعار تسرد أربعين نقطة نهاية تبدو أكثر قدرة من صفحة تسرد خمس عشرة. وهي أيضًا، في كثير من الأحيان، علامة تحذير. فبناء نقطة نهاية جزء صغير من العمل اللازم لجعلها قابلة للاستخدام. والباقي هو التوثيق: أوصاف واضحة للمعاملات، وأمثلة حقيقية للطلبات والاستجابات، وملاحظات صادقة عن الحالات الحدية، وشرح بسيط لما يحدث حين يسوء شيء ما. تخطَّ هذا العمل عبر أربعين نقطة نهاية وستحصل على أربعين ميزة موجودة تقنيًا وتكاد لا توجد عمليًا.
نفضّل أن يكون لدينا عدد أقل من الأشياء الموثقة جيدًا على عدد أكبر من الأشياء الموثقة بشكل سيئ. فالمطور الذي يقيّم واجهة API نادرًا ما يقرأ قائمة الميزات أولًا. بل يقرأ التوثيق، ويجرّب مثال طلب، ويكوّن رأيًا عن الشركة بأكملها خلال الدقائق الأولى بناءً على ما إذا كان ذلك المثال يعمل فعلًا كما هو مكتوب. وإن لم يعمل، يتوقف عدد الميزات على الصفحة التسويقية عن أن يكون مهمًا، لأن الثقة اللازمة لمواصلة القراءة قد غادرت للتو.
التوثيق الجيد بالنسبة لنا يعني بضعة أشياء ملموسة، لا التزامًا مبهمًا. يعني أن المصادقة مشروحة مع عرض كل طريقة مقبولة بوضوح، لا الطريقة التي يفضلها المزود فقط. ويعني أن حدود معدل الطلبات مذكورة بأرقام حقيقية، لا بعبارة «تُطبق حدود سخية». ويعني أن رموز الأخطاء مدرجة مع ما يسبب كلًا منها فعلًا، حتى يتمكن المطور الذي يصحح طلبًا فاشلًا من إيجاد الإجابة في التوثيق بدل التخمين من رمز الحالة وحده. لا شيء من هذا يتطلب مزيدًا من الهندسة. إنه يتطلب أن يقرر أحدهم أن كتابة ذلك بوضوح ليست عملًا شكليًا اختياريًا ملحقًا بالمنتج الحقيقي.
وهناك أيضًا تكلفة متراكمة للتوثيق الذي لا يتجاوز كونه مقبولًا. فالمطور الذي لا يجد إجابة في التوثيق يفتح تذكرة دعم، وعندها يكلّف حل ذلك السؤال الواحد وقت الموظفين فوق الوقت الهندسي الذي أُنفق أصلًا في بناء الميزة. اضرب ذلك في عدد كافٍ من العملاء الذين يصطدمون بالفقرة الغامضة نفسها، وسرعان ما تتحول «الوفورات» الناتجة عن كتابة توثيق هزيل إلى خسارة. التوثيق الواضح ليس ميزة إضافية لطيفة فوق واجهة API. إنه أرخص من البديل، بمجرد أن تحتسب عبء الدعم الذي تولّده فقرة غامضة.
ونرى أيضًا أن جودة التوثيق من الإشارات القليلة التي يستطيع العميل المحتمل تقييمها فعلًا قبل الالتزام بعملية دمج. فلا يمكنك بسهولة اختبار سجل مدة تشغيل مزود في خمس دقائق، ولا يمكنك الحكم الكامل على دقة البيانات دون الدمج أولًا. لكن يمكنك، في خمس دقائق، أن تقرأ التوثيق وتحكم ما إذا كانت الشركة التي كتبته فهمت المنتج بما يكفي لشرحه ببساطة، أم أن التوثيق يبدو كفكرة لاحقة أُلصقت بقائمة ميزات بُنيت لصفحة مبيعات.
كتابة قائمة ميزات طويلة أمر سهل. أما التوثيق الذي يستطيع المطور البناء عليه فعلًا من المحاولة الأولى فليس كذلك، وهذا الفرق هو بالضبط سبب أهميته الأكبر.