جهانِ بهترین APIها شباهت‌ها و تفاوت‌های زیادی دارد، اما یک چیز تقریباً میان همهٔ آن‌ها مشترک است: مستندات عالی.
ادغام API بدون مستندات محکم می‌تواند کابوسی واقعی باشد و بسیاری از توسعه‌دهندگان را به تسلیم شدن وادار کند. به هر شکلی نگاه کنید، نمی‌توان اهمیت مستندات API را دست‌کم گرفت.
در اجلاس API آستین ۲۰۲۴، لورا روبین، نویسندهٔ ارشد فنی در Nylas، دربارهٔ بهبود تجربهٔ مستندسازی برای خوانندگان و نویسندگان با ما صحبت کرد. به گفتهٔ روبین، معمولاً میان انتظارات مصرف‌کنندگان و واقعیت مستندات عجولانه نوشته‌شده، یک فاصلهٔ جدی وجود دارد. در ادامه، نکات مهم و بینش‌های کاربردی از صحبت‌های روبین را مرور می‌کنیم.
شناسایی نیاز به مستندات بهتر
معیارهای مختلفی برای ارزیابی کیفیت مستندات API وجود دارد. روبین در سخنانش چند نشانهٔ رایج را مطرح می‌کند که معمولاً بیانگر نیاز به بهبود مستندات هستند:
-
زمان‌های طولانی برای پیاده‌سازی یا نرخ بالای رها کردن فرآیند
-
حجم زیاد تیکت‌های پشتیبانی یا Issues در پروژه‌های متن‌باز
-
طولانی شدن چرخهٔ فروش (به‌ویژه برای APIهایی که محصول هستند)
-
پایین بودن امتیاز NPS، معیاری برای سنجش تجربهٔ مشتری
او به‌طور طعنه‌آمیز توضیح می‌دهد که رشد سریع معمولاً یکی از علل ایجاد این مشکلات است. هرچند رشد برای شرکت‌های کوچک اتفاقی مثبت است، اما می‌تواند محیطی پر فشار ایجاد کند که در آن زمان کم و سازمان‌دهی بسیار محدود است. این روند اغلب منجر به ترس، عدم قطعیت و تردید (FUD) می‌شود.
روبین می‌گوید: «وقتی گروهی پراکنده از افراد مشغول نوشتن مستندات هستند، نمی‌دانید چه کسی نوشته، کی نوشته، چرا نوشته، آیا تمام شده یا اینکه کسی آن را ویرایش کرده یا نه.»
این وضعیت باعث می‌شود زمان بیشتری صرف جنگیدن با ابزارها یا تلاش برای فهمیدن محل نیاز به نوشتن شود، به‌جای اینکه واقعاً محتوای مفید تولید شود.
البته فهمیدن اینکه مستندات نیاز به بهبود دارند، تنها نیمی از مسیر است. مرحلهٔ بعد، تشخیص این است که کجا و چگونه باید آن‌ها را بهتر کرد.
یافتن بخش‌های مناسب برای بهبود
توسعه‌دهندگان آن‌قدر به محصول نزدیک می‌شوند که دیگر نمی‌توانند از دید یک تازه‌کار به آن نگاه کنند. بنابراین، پاسخ به سؤال «آیا یک فرد جدید می‌تواند تنها با خواندن مستندات از محصول استفاده کند؟» دشوار می‌شود.
روبین پیشنهاد می‌کند از نیروهای تازه‌وارد کمک بگیرید؛ البته به شرطی که هنگام استخدام مجبور به کار با APIهای شما نشده باشند.
اگر نیروی تازه‌وارد ندارید، تیم پشتیبانی منبعی بسیار ارزشمند است. روبین با شوخی می‌گوید: «آن‌ها می‌دانند جنازه‌ها کجا دفن شده‌اند!» آن‌ها می‌توانند گزارش باگ‌ها، مشکلات متداول UX، مسیرهایی که معمولاً کاربران را برای شفافیت به آن هدایت می‌کنند و موارد مشابه را به شما بدهند.
با این حال، روبین یادآور می‌شود که «مستندات جایگزینی برای توسعهٔ خوب نیست». گاهی نویسندگان مستندات می‌توانند دور برخی مشکلات UX بنویسند، اما همیشه این‌طور نیست. او پیشنهاد می‌دهد: «اگر با یک مهندس نزدیک کار می‌کنید، زمان خوبی است که بگویید: به‌جای اینکه این را ID صدا کنیم، می‌توانیم بگوییم calendar ID که واضح‌تر باشد؟»
می‌توانید فرصتی برای دریافت بازخورد مستقیم کاربران نیز اضافه کنید: لینک ایمیل در انتهای هر صفحه، گزینهٔ «آیا این مفید بود؟» با علامت شست بالا/پایین و …
اما روبین هشدار می‌دهد: «آن‌ها به شما دروغ خواهند گفت. عصبانی هستند، اما از نوشتن حرف‌های تند و زننده در یک باکس خجالت می‌کشند.»
یک جایگزین بهتر، استفاده از آنالیتیکس، لاگ جستجو و ابزارهایی است که رفتار واقعی کاربران را نشان می‌دهد. همچنین می‌توان نرخ پرش یا تعداد صفحات ارجاع‌شده از منابع مختلف را بررسی کرد. روبین می‌گوید:
«این چیزها دروغ نمی‌گویند.»
نکات عمومی برای مستندسازی
روبین به‌عنوان یک نویسندهٔ فنی با تجربه، توصیه‌های زیادی برای کسانی دارد که می‌خواهند مستندات بهتری بنویسند. یکی از نکات او این است که مواد مفید برای توسعه‌دهندگان فراهم کنید:
«نمونه‌کدها، مثال‌ها، سناریوهای کاربردی. این چیزها عالی هستند — حتی اگر دقیقاً همان چیزی نباشند که کاربر قرار است بسازد. نگذارید حدس بزنند خروجی نهایی چه شکلی است.»
او توصیه می‌کند که دیدگاهی کل‌نگرانه‌تر نسبت به مستندات داشته باشیم:
«ممکن است یک endpoint کاملاً توصیف شده باشد، اما اگر کاربر نداند چگونه با بقیهٔ اجزا هماهنگ می‌شود، همه چیز شبیه تکه‌تکه‌هایی از یک پازل خواهد بود، در حالی که کاربران دنبال دستورالعمل هستند.»
او ادامه می‌دهد:
«سازمان‌یافته باشید — حتی اگر فقط چیزها را بر اساس حروف الفبا دسته‌بندی کنید. خوانندگان همیشه فرض می‌کنند که نظم موجود دلیل دارد.»
او تأکید می‌کند که باید به نگهدارندگان مستندات نیز فکر کرد:
«وقتی مستندات خوب نوشته شد، قابل‌استفاده بودن آن برای نگهدارندگان، همان چیزی است که باعث می‌شود مستندات خوب باقی بمانند.»
در عمل، این چطور است؟
-
مالکیت مشخص: صاحب مستندات باشید، شریک باشید یا تقسیم کنید، اما مسئولیت باید روشن باشد.
-
همه چیز را ثبت کنید: روش‌ها و موارد لازم را برای نگهدارندگان آینده بنویسید.
-
پیشرفت بهتر از کمال: از فرآیند تکرارشونده نترسید.
-
ابزارهای نظر‌محور: پلاگین‌ها، لینترها و ابزارهای خودکار برای کاهش فرسودگی تصمیم‌گیری.
-
یکپارچگی: یک مدل ذهنی بسازید که کاربران بتوانند در همهٔ محصولات یا خدمات دنبال کنند.
در این بخش، او مدل Similar Hallways را نیز یادآوری می‌کند: «حتی اگر فکر نکنید، خوانندگان همیشه دنبال الگو هستند.»
مثل یک نویسنده فکر کنید (چون هستید!)
روبین می‌گوید که نوشتن خوب، شرط لازم مستندات خوب است.
و گرچه مستندات API رمان نیست، اما ویژگی‌های زیادی با نثر سادهٔ نویسندگانی مثل همینگوی یا اشتاین‌بک مشترک دارد:
-
کلمات اضافی را حذف کنید.
-
از گذشته و مجهول پرهیز کنید.
-
از واژه‌های ساده و بدون اصطلاحات عامیانه استفاده کنید.
-
افشای تدریجی — یک‌باره اطلاعات را خالی نکنید.
-
از اصطلاحات پیچیده فقط در صورت ضرورت استفاده کنید.
-
با اعتماد به نفس بنویسید:
«نگویید باید یک ۲۰۰ برگرداند — برمی‌گرداند!»
همچنان که APIها نسخه‌گذاری و متروکه می‌شوند، مستندات نیز باید همراه آن‌ها تکامل پیدا کنند. مستندات خوب یک مقصد نیست، یک فرآیند چرخه‌ای است.
او در پایان یادآوری می‌کند: مانند یک نویسندهٔ بزرگ فکر کنید — تمرکزتان کمتر روی خودتان و بیشتر روی خواننده باشد:
- آن‌ها چه انتظاری دارند؟
- با چه الگوهایی آشنا هستند؟
- آیا داستان شما را می‌فهمند؟
هیچ‌کس نگفته نوشتن مستندات عالی آسان است!
