نویسندگان فنی قهرمانان ناشناخته دنیای APIها هستند. این افراد اغلب مسئول مستندسازی، آموزشها، نمونهکدها و محتوای بلاگ هستند و گاهی حتی در ترویج برای توسعهدهندگان مشارکت دارند، که آنها را به بازوی مهم بازاریابی برای هر محصول API تبدیل میکند.
به گفته Ken Cenerelli، نویسنده ارشد فنی در گوگل، نویسندگان فنی معمولاً بر محتوای چندین برنامه API نظارت دارند و دید وسیعی دارند. تعامل با نویسندگان فنی بهطور فزایندهای به عنصری مهم برای خلق APIهایی با تجربه توسعهدهنده باکیفیت تبدیل شده است.
Ken پس از ۱۴ سال کار بهعنوان توسعهدهنده نرمافزار، اکنون نویسنده ارشد فنی در Google Cloud است و روی مستندات API کار میکند که هر سال میلیونها بازدید دریافت میکند. طبیعتاً Ken دیدگاه منحصربهفردی نسبت به نقش نویسنده فنی و ارزشی که آنها به پروژههای API میآورند دارد.
وظایف یک نویسنده فنی در حوزه API چیست؟
نویسنده فنی API عمدتاً «راهنماهای عملی» برای استفاده از APIها مینویسد. در گوگل، این وظایف شامل نوشتن و ویرایش توضیحات کد در مستندات مرجع API، توسعه مقالات معرفی برای مفاهیم به کاربران و همکاری با تیمهای روابط توسعهدهنده برای ساخت آموزشها و نمونهکدها نیز میشود. همچنین با مدیران محصول همکاری میکنند تا نقاط پایانی جدید را مستند کنند و بررسی کنند آیا کمبود محتوایی وجود دارد یا نه.
نویسندگان فنی API امروزه چندزبانهتر شدهاند و ویدیو تولید میکنند، در کنفرانسهای توسعهدهنده سخنرانی دارند و حتی برای LLMها پرسشنامه مینویسند.
چرا تعامل با نویسندگان فنی برای بازاریابی APIها مهم است؟
نویسندگان فنی یکی از معدود گروههایی هستند که میتوانند گسترهٔ کامل APIهای سازمان را ببینند. تیمهای توسعه ممکن است بهصورت جزیرهای کار کنند و ندانند همهٔ قطعات چگونه به هم متصل هستند، اما نویسندگان فنی اغلب روی چندین API کار میکنند و تصویر کلی را میبینند. آنها میدانند نقاط پایانی API کجا همپوشانی دارند و هر نقطه چه دادهای ارائه میکند. تعامل با آنها میتواند زمان تیمهای توسعه را با برجسته کردن محصولات موجود یا هماهنگی بین تیمهای پراکنده صرفهجویی کند.
مزایای دیگر:
-
درک کامل مسیر توسعهدهنده در نحوه توسعه API روی سیستمی که مستندسازی میکنیم
-
ثبت و ارائه نمونههای کاربرد API برای توسعهدهندگان
-
راهنمایی توسعهدهندگان برای ترکیب نقاط پایانی مختلف جهت بهبود برنامههایشان
اشتباهات رایج در مستندات API
توسعهدهندگان API با سرعت بالا حرکت میکنند و اغلب آموزشها و نمونهکدهای بیشتری میخواهند. این موضوعی است که نویسندگان فنی سعی در فراهم کردن منابع بیشتر برای آن دارند. در آینده، هوش مصنوعی میتواند در تولید و تأیید سریع نمونهکد به نویسندگان فنی کمک کند.
علاوه بر این، برخی مستندات نیاز به توضیح بهتر اصول اولیه API دارند. فرضیات زیادی دربارهٔ دانش پایه وجود دارد یا توضیح کافی دربارهٔ مفاهیم بنیادی ارائه نشده است. نویسندگان فنی باید میان توسعهدهندگان مبتدی و پیشرفته تعادل ایجاد کنند.
همچنین توسعهدهندگان API دوست دارند نقاط پایانی را آزمایش کنند تا ببینند چه دادهای بازمیگردد، بنابراین ارائه نمونه curl یا یک محیط شبیهسازی API ضروری است.
نمونههای مستندات عالی توسعهدهنده
بسیاری از مستندات توسعهدهنده خوب وجود دارند، اما اثرگذاری آنها تنها با تجربه توسعهدهندگان سنجیده میشود.
از نظر سبک، مستندات مالی Plaid و Stripe جذاب و قابل پیگیری هستند. مستندات برنامههای بهرهوری مانند Box و Trello نیز ساختار خوبی دارند. همچنین مستندات Google Workspace APIs هم مورد علاقه نویسنده است.
تفاوت نوشتن برای کاربران داخلی و خارجی
Ken تجربهای فقط در تولید مستندات برای مخاطبان خارجی دارد. برای کاربران داخلی، نویسنده میتواند سطح دانش و آشنایی بیشتری فرض کند و برخی مراحل پیشنیاز را حذف کند. همچنین اصطلاحات و اختصارات داخلی سازمان ممکن است قابل استفاده باشند.
انتظارات سبک نویسندگی فنی
راهنماهای سبک میان نویسندگان فنی اختلاف ایجاد میکنند. برخی بهطور دقیق از آن پیروی میکنند و برخی انعطاف دارند. برای Ken، رعایت سبک و راهنما چارچوب لازم برای نوشتن مستندات را فراهم میکند و زمان ویرایش را کاهش میدهد.
هیجان برای Austin API Summit
Ken از ارائه دوباره سخنرانی خود هیجانزده است و فرصت خوبی برای آموزش اهمیت نویسندگان فنی است. همچنین مشتاق دیدن سخنرانیهای دیگران و بازدید از شهر و دفاتر گوگل در Austin است.
پیام به شرکتکنندگان
Ken امیدوار است شرکتکنندگان با درک اهمیت نویسندگان فنی برای ایجاد APIها، نحوه همکاری با آنها و ادغام آنها در کل فرآیند توسعه آشنا شوند و آنها را بهعنوان بخشی مهم از تیم خود ببینند.
تگها: ، مستندات API، تجربه توسعهدهنده، بازاریابی API، کنفرانس Austin
