تصور کنید کاربر شما هنگام تنظیم یک API با گزینه‌ای ناشناخته مواجه می‌شود و برای یافتن پاسخ، مجبور است اپلیکیشن را رها کرده و تب جدیدی برای جست‌وجو در مستندات باز کند. این گسست در جریان کاری، احتمال خروج کاربر یا سردرگمی او را به‌شدت افزایش می‌دهد. کاربر ممکن است پیش از بازگشت به اپلیکیشن برای به پایان رساندن کار خود، سه صفحه مختلف از مستندات را مرور کند.
Documentation.AI با جاسازی صفحات مستندات و یک دستیار هوش مصنوعی مستند-محور مستقیماً در رابط کاربری محصول، این اصطکاک را از بین می‌برد تا کاربر هرگز صفحه فعلی خود را ترک نکند.
bسیاری از محصولات نرم‌افزاری از شکافی میان «نقطه ابهام» و «پاسخ موجود» رنج می‌برند. حتی اگر مستندات دقیق باشند، عمل جابه‌جایی از ابزار به یک مرکز کمک مجزا، بار شناختی کاربر را زیاد کرده و ریسک ریزش (Drop-off) را افزایش می‌دهد. Documentation.AI با تبدیل مستندات به یک لایه زمینه‌ای — شبیه به یک راهنمای هوشمند که هم‌زمان با شما در صفحه حضور دارد — به جای یک مقصد مجزا، این مشکل را حل می‌کند.
به نقل از راهنمای منتشرشده در ۱۳ اکتبر ۲۰۲۶، این پلتفرم محیطی بومی برای مستندات محصول، مراجع API و مراکز کمک فراهم می‌کند. ارزش اصلی این سیستم در یکپارچگی و ثبات است: دستیار جاسازی‌شده از همان پاسخ‌ها و ارجاعاتی استفاده می‌کند که در سایت اصلی مستندات وجود دارد. همچنین صفحات مستندات مستقیماً از سایت شما بارگذاری می‌شوند تا ظاهر آن‌ها دقیقاً مشابه نسخه اصلی باشد. این رویکرد تضمین می‌کند که در تمام نقاط تماس کاربر، یک «منبع واحد حقیقت» (Single Source of Truth) حفظ شود.
همان‌طور که در تحلیل‌های قبلی ما درباره‌ی استراتژی‌های کاهش نرخ ریزش کاربر اشاره کردیم، هر ثانیه تأخیر در یافتن پاسخ، احتمال ترک محصول را افزایش می‌دهد.
زمینه و الزامات
این سیستم زمانی بیشترین اثر را دارد که کاربران شما به‌طور منظم برای یافتن اطلاعات از محصول خارج شوند یا زمانی که بخواهید همان پاسخ‌های مستند-محور و دارای ارجاع سایت مستندات را در داخل اپلیکیشن خود داشته باشید. فرآیند راه‌اندازی به‌گونه‌ای طراحی شده که کمترین تلاش را طلب کند و تنها به یک کلید جاسازی (Embed Key) و یک تکه کد (Snippet) نیاز دارد.
با این حال، طبق مستندات این سرویس، برخی پیکربندی‌ها نیاز به برنامه‌ریزی پیش‌دستانه دارند:
- مستندات منتشرنشده: مستندات شما باید پیش از جاسازی، منتشر شده باشند و در داشبورد در وضعیت Live نمایش داده شوند.
- دامنه‌های زیرمسیر: اگر مستندات روی یک زیرمسیر (Subpath) از دامنه خودتان ارائه می‌شوند، باید تعدادی قوانین Reverse Proxy را پیکربندی کنید.
- مستندات خصوصی: اگر مستندات شما خصوصی هستند، کاربران برای دسترسی به آن‌ها باید یک مرحله احراز هویت (Sign-in) اضافی را طی کنند.
سازوکار جاسازی
پیاده‌سازی این سیستم شامل سه گام اصلی است: ایجاد کلید، افزودن کد و تأیید منشأ (Origin). برای انجام این اقدامات، کاربر باید نقش Admin در سازمان خود داشته باشد.
گام اول: ایجاد کلید جاسازی
در داشبورد و در مسیر Settings > Embed، کاربر با کلیک روی Create key سه فیلد مشخص را پر می‌کند:
- نام (Name): یک برچسب برای استفاده داخلی (مثلاً "Web app" یا "Blog Demo").
- منشأهای مجاز (Allowed origins): هر سایتی که قرار است مستندات در آن نمایش داده شوند (مثلاً
https://app.example.com). برای توسعه محلی، باید سرور توسعه خود را مانندhttp://localhost:5173اضافه کنید. - تاریخ انقضا (Expires): گزینه‌های موجود شامل Never، ۳۰ روز، ۹۰ روز، ۱۸۰ روز یا ۱ سال است.
سه قانون سخت‌گیرانه برای منشأها وجود دارد: اول اینکه نباید مسیر (Path) داشته باشند (مثلاً https://app.example.com:8443 صحیح است). دوم اینکه باید از HTTPS استفاده کنند (استفاده از HTTP معمولی فقط برای localhost، 127.0.0.1 و [::1] مجاز است). سوم اینکه از کاراکترهای جایگزین (Wildcards) پشتیبانی نمی‌شود. شما باید تک‌تک محیط‌ها، از جمله Production، Staging و Local را لیست کنید.
برای تأمین امنیت یکپارچگی، پلتفرم از یک سیستم دوکلیدی استفاده می‌کند. کلید منتشرشدنی (pk_...) در کد صفحه قرار می‌گیرد و محدود به منشأهای مجاز است. کلید محرمانه (sk_...) تنها یک‌بار نمایش داده می‌شود، فقط برای مستندات خصوصی مورد نیاز است و باید در سرور شما باقی بماند.
گام دوم: افزودن تکه کد
یکپارچگی از طریق یک تکه کد HTML انجام می‌شود که باید پیش از تگ بسته </body> قرار گیرد. پیاده‌سازی پایه به این شکل است:
`
`بسیار حیاتی است که ویژگی type="module" روی اسکریپت حفظ شود تا اجرای کد تا زمان بارگذاری کامل اسکریپت جاسازی منتظر بماند. برای کسانی که از فریم‌ورک‌های مدرن مانند React، Next.js یا Vue استفاده می‌کنند، پلتفرم یک بسته اختصاصی @documentation.ai/embed برای مدیریت مقداردهی اولیه در محیط مرورگر ارائه داده است.
گام سوم: بررسی عملکرد
صفحه را در یکی از منشأهای مجاز باز کنید. شما باید اولین صفحه مستندات خود را به همراه دستیار هوش مصنوعی در گوشه صفحه ببینید. در صورت عدم موفقیت، کنسول مرورگر را برای پیام‌های [DocumentationAI] بررسی کنید:
origin_not_allowed: منشأ دقیق، شامل پورت، در لیست کلید تعریف نشده است.publishable_key_invalidیاpublishable_key_expired: کلید باید دوباره کپی شود یا از نو ساخته شود.
الگوهای استقرار
بسته به نیاز کاربر، توسعه‌دهندگان می‌توانند از چهار الگوی متمایز برای جاسازی انتخاب کنند:
- مستندات در صفحه (Docs in Page): رندر کامل یک صفحه مستندات در داخل یک صفحه از محصول. این حالت برای کاربرانی که نیاز دارند یک راهنمای کامل را در کنار یک فرم تنظیمات بخوانند، ایده‌آل است.
- چت هوش مصنوعی در صفحه (AI Chat in Page): یک دستیار هوش مصنوعی دارای ارجاع برای پرسش‌های مستقیم. این قابلیت به کاربران اجازه می‌دهد بدون جست‌وجو، سوالات خود را به زبان ساده بپرسند.
- پنل‌های شناور (Floating Panels): یک دکمه کمک یا نوار "Ask AI" که در صورت نیاز باز می‌شوند. دکمه کمک را می‌توان با یک پیام خوش‌آمدگویی (مثلاً "چطور می‌توانیم کمک کنیم؟") مقداردهی کرد، در حالی که نوار Ask AI را می‌توان در موقعیت
bottom-centerصفحه قرار داد. - لینک‌های کمک (Help Links): ویژگی‌های (Attributes) HTML که صفحات خاصی از مستندات را در کنار یک دکمه یا لینک باز می‌کنند. این‌ها به هیچ جاوااسکریپتی فراتر از
init()نیاز ندارند. برای مثال، یک لینک می‌تواند ازdata-documentation-ai-navigate="/customize/branding"استفاده کند (با یکhrefواقعی به عنوان جایگزین) یا یک دکمه ازdata-documentation-ai-ask="How do I export my data?"بهره ببرد.
یک صفحه واحد می‌تواند هر تعداد ویجت داخلی (Inline) را پشتیبانی کند، اما تنها یک ویجت شناور (Floating) مجاز است.
عملکرد دستیار هوش مصنوعی
این دستیار تنها متن تولید نمی‌کند، بلکه پاسخ‌ها را با لینک‌های مستقیم به صفحات منبع برمی‌گرداند. این فرآیند خطر توهم (Hallucination) را با متکی کردن هوش مصنوعی به مستندات ارائه شده، به‌شدت کاهش می‌دهد. این رویکرد در واقع پاسخی به چالش‌های رایج در دستیارهای هوش مصنوعی است که گاهی به جای تحلیل دقیق ساختار پروژه، به حدس‌های تصادفی متکی می‌شوند؛ موضوعی که در تحلیل ما درباره نقشه‌راه اجرای کد در برابر حدس‌های AI به تفصیل بررسی شده است.
برای نویسندگان فنی، این موضوع یک مسئولیت خاص ایجاد می‌کند: دستیار تنها به اندازه کیفیت مستندات زیربنایی موثر است. پیش از عرضه، نویسندگان باید سوالاتی را که کاربران واقعاً می‌پرسند تست کنند، ارجاعات را دنبال کنند و نقاط ضعف مستندات را شناسایی نمایند. در این راستا، بررسی دقیق خروجی‌ها برای اطمینان از صحت پاسخ‌ها بسیار حیاتی است، چرا که همان‌طور که پیش‌تر اشاره کردیم، بازرسی خروجی‌ها می‌تواند در بسیاری از موارد موثرتر از مهندسی پیچیده پرامپت باشد.
دستیار جاسازی‌شده دقیقاً مشابه دستیار سایت مستندات است، به این معنی که هر بهبودی در محتوای منبع، بلافاصله تجربه کاربر در داخل اپلیکیشن را بهبود می‌بخشد.
مقایسه بازار: Documentation.AI در برابر GitBook
به گزارش بررسی قیمت‌ها در اکتبر ۲۰۲۶، نقطه ورود برای جاسازی در این دو سرویس تفاوت چشم‌گیری دارد.
قیمت‌گذاری Documentation.AI:
- Starter: رایگان (0 دلار)، ۵ صندلی ویرایشگر، ۱۰ هزار اعتبار AI یک‌باره. شامل مستندات جاسازی‌شده و دستیار AI.
- Standard: ۵۵ دلار ماهانه (در صورت پرداخت سالانه / ۶۹ دلار ماهانه)، ۱۰ صندلی ویرایشگر، ۱۰ هزار اعتبار AI ماهانه.
- Pro: ۱۵۹ دلار ماهانه (در صورت پرداخت سالانه / ۱۹۹ دلار ماهانه)، صندلی ویرایشگر نامحدود، ۳۰ هزار اعتبار AI ماهانه.
قیمت‌گذاری GitBook:
- Free: رایگان، ۱ کاربر.
- Essential: ۶۵ دلار ماهانه برای هر سایت + ۱۲ دلار ماهانه برای هر کاربر (پرداخت سالانه)، ۲ هزار اعتبار AI ماهانه.
- Ultimate: ۲۴۹ دلار ماهانه برای هر سایت + ۱۲ دلار ماهانه برای هر کاربر (پرداخت سالانه)، ۱۰ هزار اعتبار AI ماهانه. این حداقل پلنی است که برای جاسازی دستیار (Assistant embed) مورد نیاز است.
سازوکار اعتبارها:
در Documentation.AI هر پرسش بدون توجه به طول آن، ۱۰ اعتبار هزینه دارد. با اتمام اعتبارها، هیچ صورت‌حساب اضافه‌ای صادر نمی‌شود و هوش مصنوعی صرفاً تا چرخه ۳۰ روزه بعدی یا شارژ مجدد متوقف می‌شود. در مقابل، GitBook برای هر پرسش مرتبط ۲۰ اعتبار کسر می‌کند و بسته‌های اعتبار ماهانه (مثلاً ۵ هزار اعتبار با ۴۷.۵۰ دلار تا ۴۰ هزار اعتبار با ۳۰۰ دلار) ارائه می‌دهد و با اتمام اعتبار، استفاده از سرویس به‌طور خودکار متوقف می‌شود.
چک‌لیست پیش از استقرار
پلتفرم پیش از استقرار در محیط Production، چندین بررسی امنیتی و کیفی را توصیه می‌کند:
- دقت محتوا: مستندات منبع را دقیق نگه دارید؛ یک ویجت نمی‌تواند دستورالعمل‌های قدیمی را جبران کند.
- امنیت منشأ: منشأهای مجاز را در محیط عملیاتی به HTTPS محدود کنید. برای هر محصول یا محیط از کلیدهای مجزا استفاده کنید تا بتوانید یکی را بدون تأثیر بر دیگران ابطال کنید.
- مدیریت کلیدها: اطمینان حاصل کنید که کلید محرمانه (Secret Key) در سرور باقی بماند. مستندات عمومی تنها به کلید منتشرشدنی نیاز دارند.
- تست عملکردی: پاسخ‌ها را تست کنید، نه فقط رندر شدن ویجت را. سوالات واقعی بپرسید، ارجاعات را تأیید کنید و پنل را در دستگاه‌های موبایل بررسی کنید، جایی که پنل‌های کمک اغلب تمام صفحه را می‌پوشانند.
این تغییر به سمت «مستندات داخل اپلیکیشن» نشان‌دهنده یک روند گسترده‌تر است که در آن مرکز کمک دیگر یک مقصد نیست، بلکه سرویسی است که کاربر را دنبال می‌کند. شرکت‌ها با کاهش فاصله تا پاسخ، احتمالاً می‌توانند پذیرش ویژگی‌ها (Feature Adoption) را افزایش و تعداد تیکت‌های پشتیبانی را کاهش دهند.
برای شروع، توسعه‌دهندگان می‌توانند یک حساب رایگان بسازند و یکپارچگی را روی یک صفحه با اصطکاک بالا تست کنند تا تأثیر آن را بر موفقیت کاربر اندازه‌گیری نمایند.
اما هزینه استنتاج این مدل‌ها در مقیاس بالا چالش اصلی است — به تحلیل ما درباره‌ی بهینه‌سازی هزینه‌های API مراجعه کنید.
گفتگو