۵ نکته برای نوشتن اسناد API بهتر

مستندات عالی API برای یک تجربه توسعه دهنده خوب ضروری است. اما مستندات شما باید برای غیر توسعه دهندگان نیز عالی باشد.

هنگامی که نرم‌افزار به صورت آنلاین منتقل شد، اسناد نیز تغییر کردند. امروزه، اسناد میزبانی شده عادی است. اما در حالی که قالب ها و روش های تحویل اسناد تغییر کرده است، هدف اساسی توضیح نرم افزار تغییر نکرده است.

در هر صورت، نوشتن اسناد خوب در سال‌های اخیر دشوارتر شده است. پیچیدگی اطلاعات مورد نیاز برای پشتیبانی از محصولات نرم افزاری به طور چشمگیری افزایش یافته است. در عین حال، مخاطبان مستندسازی بیشتر و متنوع‌تر شده‌اند.

برای بسیاری از کاربران نرم افزار ما، مستندات اولین برداشت آنها را از محصولات، افراد و برند ما ایجاد می کند. و هیچ کس اسناد و مدارک ضعیف را دوست ندارد. من فکر می‌کنم همه ما می‌توانیم حداقل یک تجربه را بازگو کنیم که در آن اسناد ناکافی ما را از یک محصول دور کرد و هرگز به گذشته نگاه نکردیم.

این مانع برای کاربران شما که از زمینه‌های فرهنگی، جغرافیایی و آموزشی متنوعی هستند، حتی بالاتر است. ایجاد یک تجربه مستندسازی که برای همه مناسب باشد، برای فراگیر بودن، برای همتایان تجاری غیر فنی شما و برای تجربه توسعه دهنده بهتر است. امروزه خوانندگان اسناد نرم افزاری می توانند هر کسی باشند.

اطمینان از تجربه مستندسازی خوب به معنای ایجاد محیطی است که هر کسی بتواند به راحتی اسناد شما را هضم کند. این بدان معناست که مستندات شما باید فاقد اصطلاحات تخصصی باشد و باید شامل قابلیت‌های «امتحان کن» باشد که به افراد اجازه می‌دهد آزمایش کنند، نمونه‌هایی را ارائه کنند که افراد بتوانند از آنها به عنوان نقطه شروع استفاده کنند، و شامل اطلاعات نحوه انجام به همراه مشخصات API واقعی باشد. مستندات قانع‌کننده، آموزشی و فراگیر، به نوبه خود، تجربه توسعه‌دهنده‌ای را ایجاد می‌کند که از فن‌آوران از همه زمینه‌ها دعوت می‌کند.

در اینجا پنج نکته برای بهبود اسناد API برای هر کاربر، به ویژه برای کمک به کاربرانی با پیشینه‌های غیر سنتی وجود دارد.

برای ثبات تلاش کنید

سازگاری اصطلاحات، سبک، و سازمان‌دهی از ویژگی‌های همه ارتباطات خوب است. این باید پایه اصلی کل برنامه API و فرآیند مستندسازی شما باشد. برای ایجاد یکپارچگی مناسب در سراسر مستندات خود، مطمئن شوید که سبک و رویکرد نوشتن در سراسر تیم نویسندگان شما یکسان است.

با پیاده‌سازی ویژگی‌ای مانند API راهنماهای سبک، سازگاری را در کل سطح برنامه API خود فعال کنید. /a> برای کمک به مدیریت و حفظ ثبات در گروه. روی سازماندهی عملی، قابل پیش‌بینی و پیشنهادات ثابت در سراسر مستندات خود تمرکز کنید تا تجربه توسعه‌دهنده بهتری ایجاد کنید و راحتی بیشتری را برای همه انواع توسعه‌دهندگانی که با اسناد شما روبرو می‌شوند، صرف‌نظر از پیشینه‌شان، فراهم کنید.

پیروی از استانداردهای صنعتی برای اسناد شما، مانند OpenAPI، همچنین می‌تواند به کاربران جدید کمک کند تا به سرعت خود را به سمت یک الگوی آشنا هدایت کنند و استانداردسازی بیشتری را ایجاد کنند. پاک کردن گزینه‌های پیمایش و سبک ثابت، قابلیت شناسایی را هم برای ویژگی‌ها و هم برای اسناد شما بهبود می‌بخشد.

از زبان ساده و لحن دوستانه استفاده کنید

همه از اصطلاحات واژگان متنفرند، و اجازه دهید با آن روبرو شویم—در صنعت فناوری واژه‌های صنفی بسیار زیادی وجود دارد. اصطلاحات اصطلاحی نه تنها مانع از برقراری ارتباط واضح می شود، بلکه می تواند باعث شود خوانندگان احساس ناخوشایندی کنند. این آخرین چیزی است که می خواهید. هنگام نوشتن اسناد خود، زبان را ساده و قابل دسترس نگه دارید و بدانید که اصطلاحات تخصصی، عامیانه، جوک های داخلی، کلمات اختصاری پیچیده و موارد مشابه جایی در اسناد شما ندارند.

وقتی موضوع پیچیده است، در آن زمان است که باید نوشتن خود را ساده‌تر کنید. توجه به این نکته مهم است که برخی از کاربران ممکن است با تحصیلات رسمی نسبتا کمی به محصول شما بیایند. نوشته‌های شما باید برای طیف کامل کاربران ممکن، از توسعه‌دهندگان خودآموخته، غیر انگلیسی زبان‌ها، و توسعه‌دهندگان تازه وارد دانشگاه گرفته تا افراد حرفه‌ای با تجربه که زمان کمی برای انجام کار دارند، در دسترس باشد. با ارائه اسنادی که به راحتی قابل درک است، زندگی آنها را آسانتر کنید.

در اینجا چند نکته دیگر وجود دارد که باید هنگام تلاش برای لحن جامع و زبان ساده در اسناد خود به آنها توجه کنید: 

• به زبان تبعیض آمیز هوشیار باشید. راهنمای سبک مایکروسافت بخش مختصری در مورد ارتباطات بدون تعصب دارد که منبع بسیار خوبی است.
• از نام متغیرها و نام توابع واضح در نمونه کد استفاده کنید. از عباراتی که برای فهمیدن نیاز به آشنایی خاصی دارند اجتناب کنید.
• هرگز فرض نکنید. نیازی نیست که در هر سندی بحث مفصلی از هر مفهومی بگنجانید. هنگامی که زمان یا فضای لازم برای توضیح آن را در متن ندارید، به منبع دیگری با تعریف یا بحث عمیق پیوند دهید. تصور نکنید که خوانندگان اسناد شما همه چیز را می دانند.
• از اصطلاحات خنثی جنسیت استفاده کنید. این باید مشخص باشد. استفاده از نفر دوم (شما، شما، شما) یک راه عالی برای تقویت حس ارتباط با مخاطبان است.
• متن جایگزین به تصاویر اضافه کنید. به یاد داشته باشید، می خواهید اسناد شما برای همه قابل دسترسی باشد. متن جایگزین را برای تمام گرافیک‌ها و زیرنویس‌ها در ویدیو اضافه کنید تا برای صفحه‌خوان‌ها و سایر ابزارهای دسترسی قابل مشاهده باشد.

اطلاعات ضروری را برای موارد غیرفنی 

ارائه دهید

همه کسانی که به اسناد شما نگاه می کنند، پیشینه توسعه دهنده ندارند. مدیران محصول، رهبران کسب و کار، و حتی همکاران تیم بازاریابی ممکن است به خوبی نیاز داشته باشند از اسناد شما در برخی موارد استفاده کنند.

استفاده از مثال‌های ساده و قابل فهم در دنیای واقعی می‌تواند به درک آسان‌تر اطلاعات فنی برای خوانندگان غیر فنی کمک کند. اینجاست که «آن را امتحان کنید» یا قابلیت‌های تمسخر کردن (مانند مواردی که در مستندات Stoplight) می‌توانند اسناد شما را مفیدتر کنند. . آنها حتی می توانند API شما را برای مشتریان بالقوه جذاب تر کنند.

برای مثال، بیایید نیازهای شرکتی را در نظر بگیریم که می‌خواهد یک سیستم پرداخت را برای فروشگاه اینترنتی خود پیاده‌سازی کند. صاحب محصول یک ایده کلی از الزامات خواهد داشت. مشتریان برای وارد کردن اطلاعات پرداخت به روشی ساده و ایمن نیاز دارند. کسب و کار به راهی برای پردازش و ردیابی آن پرداخت ها نیاز دارد. سپس، پرداخت‌ها باید به سفارش‌هایی تبدیل شوند که باید انجام شوند.

مالک محصول ممکن است اولین کسی باشد که به اسناد API سیستم پرداخت نگاه می کند. آنها ممکن است بخواهند چندین API را در سطح بالایی ارزیابی کنند قبل از اینکه از یک توسعه دهنده بخواهند تجزیه و تحلیل عمیقی از آنهایی که به بهترین وجه نیازهای شرکت را برآورده می کنند انجام دهد. در این صورت، API با بهترین مستندات شانس بیشتری برای عرضه دارد. فقط به یاد داشته باشید، شخصی که اسناد شما را مصرف می کند، لزوماً از یک پیشینه توسعه دهنده نیست.

رویکرد اول طراحی را در پیش بگیرید

در Stoplight، رویکرد اول طراحی برای همه کارهایی که انجام می دهیم. این به معنای تمرکز بر ساخت API برای انسان های پشت سر آنها و در نظر گرفتن همه سهامدارانی است که ممکن است با API تعامل داشته باشند، ایجاد کنند یا مصرف کنند. همین رویکرد را می توان برای طراحی مستندات شما اعمال کرد. اسناد API شما باید با کاربران در جایی که هستند ملاقات کند و با نیازهای آنها صحبت کند. باید بیشتر از فهرستی از نقاط پایانی و روش ها باشد.

فکر کردن در مورد کاربران بالقوه خود به عنوان یک گروه متنوع با اهداف مختلف می تواند به شما کمک کند اسناد خود را سازماندهی کنید تا خلاقیت ایجاد کنید و دنیای واقعی را منعکس کنید. هنگام نوشتن اسناد خود، برای هر موردی بنویسید. هنگام پیش‌نویس اسناد خود، توسعه‌دهنده سنتی، توسعه‌دهنده غیرسنتی، همتای تجاری، شرکای احتمالی و دیدگاه‌های مصرف‌کننده نهایی همه باید در نظر گرفته شوند.

با چند رسانه ای خلاق شوید

اگر قصد دارید اسناد خود را جذاب‌تر و جامع‌تر کنید، همیشه سعی کنید راه‌هایی برای نمایش راهنماهای عملی برای پیاده‌سازی پیدا کنید. خلاق باشید، موارد استفاده از شرکت‌ها و توسعه‌دهندگان مختلف را برجسته کنید و نمونه برنامه‌ها و دستورالعمل‌های فنی را بر اساس سناریوهای دنیای واقعی ارائه دهید. از مزایای چندرسانه‌ای مانند ویدیوها، گرافیک‌ها یا گیف‌ها استفاده کنید تا اسناد خود را جذاب‌تر کنید و به کسانی که ممکن است اطلاعات را راحت‌تر در قالبی غیر از متن کاملاً جذب کنند، ارائه دهید.

این ضرب المثل قدیمی «با دیگران طوری رفتار کن که دوست داری با تو رفتار شود» در مورد خوانندگان اسناد شما صدق می کند. با در نظر گرفتن تنوع افراد و پیشینه‌هایی که ممکن است با اسناد شما روبرو شوند، بنویسید که چگونه می‌خواهید کسی چیزی را برای شما توضیح دهد. همدلی با توسعه‌دهنده و کاربر، راه اصلی برای کار به سمت توسعه‌دهنده و تجربه کاربری بهتر است.

به عنوان یک فکر نهایی، نوشتن برای همه به معنای کاهش توقعات نیست، بلکه برای گسترش آنهاست. نوشتن اسناد در دسترس تر باعث می شود افراد بیشتری محصول شما را آزمایش کنند و برای اطلاعات بیشتر بازگردند. مستندات کاملاً نوشته شده و قابل دسترسی به توسعه دهندگان سازنده تر، کاربران طولانی مدت، ادغام عمیق تر و تمایل قوی تر به برند منجر می شود.

برای منابع بیشتر در مورد نحوه نوشتن مستندات خوب، این راهنمای بهترین شیوه ها را بررسی کنید.

پم گودریچ نویسنده فنی و استراتژیست مستندسازی در Stoplight است.

—

New Tech Forum مکانی برای کاوش و بحث در مورد فناوری سازمانی نوظهور در عمق و وسعت بی سابقه ای فراهم می کند. انتخاب ذهنی است، بر اساس انتخاب ما از فناوری هایی که معتقدیم مهم هستند و برای خوانندگان InfoWorld بیشترین علاقه را دارند. InfoWorld وثیقه بازاریابی را برای انتشار نمی پذیرد و حق ویرایش تمام محتوای ارائه شده را برای خود محفوظ می دارد. همه سوالات را به newtechforum@infoworld.com ارسال کنید.