Всё для технического документирования
+7 (495) 001-40-42
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

Итак, вам нужно документировать API…

09.09.2016

01Что такое API, для чего используется, зачем и как начать его документировать, какие инструменты использовать, как взаимодействовать с коллегами, какие существуют основные принципы. Очень полезная статья для технических писателей, которые хотят роста. Начинайте документировать API, разберитесь в этом – и карьерный рост вам обеспечен! Получить первое представление вам поможет эта статья. Автор – Лоис Паттерсон (Lois Patterson), технический писатель API из компании Global Relay (Канада).


Тяжело отследить, сколько раз API (Application Programming Interfaces, интерфейсы программирования приложений) сопровождают нашу жизнь каждый день или даже каждый час. Когда проходит ваша транзакция в PayPal или когда вас подбирает водитель Uber, само по себе API невидимо, и это более чем типично для пользовательского программного обеспечения. API используется даже тогда, когда вы встраиваете YouTube-видео в запись WordPress. При наличии сотен тысяч общедоступных API, доступных широчайшему кругу пользователей, компании находятся под большим давлением, чтобы их API были легки и удобны для использования. Не будет сюрпризом то, что рост количества вакансий, связанных с документированием API, огромен — он показывает разогретый рынок для технических писателей, которые специализируются на документировании API.

Куда ни кинь взгляд, почти везде вы увидите Карты Google, потому что API Карт Google иллюстрирует простоту и удобство использования. И документация API Карт Google показывает, почему оно успешно:

API предоставляет пользователям (обычно это разработчики программного обеспечения) интерфейс, который позволяет получить то, что им нужно от вашего программного обеспечения, и интегрировать его в их приложение.

Так чего хотят пользователи API?

Что мы всегда говорим новым (и старым) техническим писателям? Узнайте ваших пользователей… и пишите c расчётом на этих пользователей. Поставьте себя на их место и поймите, что им необходимо знать, чтобы выполнить свою задачу.

Так давайте рассмотрим типичного пользователя API. Этот человек — разработчик программного обеспечения, но который, возможно, не думает о себе так. Он создаёт программное обеспечение или, вероятно, веб-страницу или запись в блоге, что требует знать, что API вашего продукта может позволить сделать из того, что он хочет предоставить своим пользователям. Возможно, ему требуется транслировать данные рынка для своих финансовых приложений или, вероятно, он хочет предложить случайный набор музыкальных треков из популярных музыкальных сервисов на своём сайте. API, которое вы предлагаете ему, является средством достижения цели, возможно, критичной для его работы, но при этом абсолютно нет интереса к нему самому. Наш пользователь API хочет заставить свой код работать с API как можно быстрее, чтобы можно было перейти к решению других проблем. Та часть кода, которая взаимодействует с вашим API, занимает малую часть всей базы кода. Ваша миссия как технического писателя API — предоставить ему документацию, которая позволит это сделать.

Начните с разработки API

Вас когда-либо просили написать документацию, чтобы решить проблему плохого качества разработки? Это ужасно. Для пользователей API, у которых нет осязаемого интерфейса продукта, плохое качество разработки даже более губительно.

API должны разрабатываться так же тщательно и вдумчиво, как создаются и стандартные пользовательские интерфейсы. Так же, как технические писатели, которые работают с разработчиками графического интерфейса, чтобы документировать API, вы должны вовлечь себя в процесс разработки с самого начала. С помощью методологии эджайл, что означает участие в спринтах разработчиков. Основные принципы разработки, такие как связность, для пользователей API даже более важны.

Как выглядит связная разработка? Давайте обратим внимание на REST API, которые наиболее популярны для использования на массовом рынке. REST (Representational State Transfer, «передача состояния управления») представляет собой набор принципов разработки API, которые зарекомендовали себя как исключительно эффективные в широком спектре очень разных API.

В типичном REST API набор существительных (объектов) взаимодействует с ограниченным набором глаголов (GET, PUT, POST, DELETE). Параметры каждого существительного должны следовать схожим шаблонам и соглашениям. Параметры должны иметь такие типы данных, которые имеют смысл и связаны между собой. Если параметр userID — строка, а customerID — число, вы введёте пользователя в заблуждение. Действия глаголов должны быть связными для всех объектов.

Pearson предлагает хороший учебник по разработке REST API, который может ответить на большинство первоначальных вопросов.

Первый опыт использования вашего API

Если вы новый пользователь сложного нового продукта, что вы в первую очередь захотите сделать? Успешно использовать его. Как указал мне эксперт по разработке документации Том Джонсон (Tom Johnson), пользователь должен иметь возможность получить быстрый успех с помощью скорейшего продвижения к «Привет, мир» при использовании API. Searchify, например, содействует использованию своего продукта с помощью этой простого урока «Привет, мир», а затем переходит к более сложным урокам.

Обратите внимание на тщательное конструирование шагов и как пользователю сообщают обо всех необходимых условиях для завершения урока. Урок позволяет пользователям выбрать язык программирования.

После того, как вы завершите первый простой урок, вы можете пройти больше уроков, чтобы изучить важные функции Searchify и научиться использовать его в ваших приложениях.

Какие инструменты и процессы использовать для документирования API?

Раньше технические писатели обычно использовали инструменты и процессы, которые были полностью отвязаны от разработки кода. Иногда документация задерживалась до того момента, пока продукт не будет завершён.

С появлением встроенной онлайн-справки, стала необходима более тесная совместная работа. При работе над документацией API необходимо избегать разделения между кодом и документацией.

Это не означает, что всё должно документироваться полностью с колеса. Например, вы можете писать документацию, необходимую для создания актуального справочника по API параллельно с кодом, но отложить написание уроков на более позднее время. Не в дальний ящик, конечно, так как вам необходимо обеспечить доступ к этой информации первым пользователям.

Давайте рассмотрим несколько инструментов, которые вы можете использовать.

Основные принципы

Как автору документации API вам необходима помощь вашей команды разработки. Если будете делать всю работу самостоятельно, это приведёт к разочарованию и дополнительной работе. Вам ещё нужно будет много чего описать, но если потребовать, чтобы разработчики документировали свой код, это сделает процесс более простым для вас, и ещё поможет команде по контролю качества.

Это требование по привлечению разработчиков к созданию документации означает, что вам нужен переносимый формат, который может быть доступен для любого текстового редактора. У вас может быть один разработчик, который работает в emacs, другой в vim, а третий в SublimeText, и никто из них не хочет изучать новый текстовый редактор. Мы все знаем, насколько привязанными могут быть технические писатели к собственным инструментом, будь то Microsoft Word или MadCap Flare, и с разработчиками то же самое. К счастью, файлы, создаваемые в различных текстовых редакторах, полностью совместимы в отличие от проприетарных инструментов. Документация API может создаваться в виде текстовых файлов, а затем обрабатываться в генераторе статичных сайтов для создания привлекательных веб-сайтов или PDF. Ниже указаны несколько текстовых редакторов, которые, как мне известно, популярны среди различных групп разработчиков:

Воздержитесь от искушения ограничивать себя, давая только нескольким людям доступ к проприетарному инструменту. Открытые инструменты — популярный выбор для документирования API, именно потому что эти документы требуют тесной совместной работы с программистами.

Markdown с генератором статичных сайтов

Markdown — популярный и несомненно вездесущий формат в наши дни. Markdown — простой язык разметки, который вы можете использовать в любом текстовом редакторе. Если у вас есть файлы, созданные в Markdown, вы затем используете генератор статических сайтов, например, Jekyll, приложение, которое преобразует файлы, созданные в Markdown, в форматы HTML, PDF и другие. Если ваша документация в формате Markdown размещена на Github, ваши документы автоматически преобразуются в HTML без каких-либо действий с вашей стороны (хотя вы можете настроить отображение).

Вы можете научиться писать на Markdown за минуты. Это просто. Разработчики из вашей команды знают и любят Markdown. Использование Markdown помогает вам убрать барьеры между командой работки и командой документирования.

У Markdown есть некоторые ограничения в смысле связи между различными наборами документов, и существует множество различных версий Markdown, потому что так много разработчиков добавляют свои любимые функции собственных версий Markdown. Однако Markdown — предпочтительный выбор многих, как вы можете увидеть, посмотрев множество примеров наборов документации API на Github.

Разметка reStructuredText с генератором статических сайтов Sphinx

reStructuredText похож на Markdown, но предоставляет больше функций и отчасти связан с разработкой в Python. Я ценю простоту, с которой вы можете делать вставки из файлов, создавать библиографические ссылки, использовать LaTeX для математических выражений и создавать связи между множеством наборов документации. Несмотря на то, что reStructuredText немного более сложен, чем Markdown, а установка вместе с генератором статических сайтов Sphinx также может принести сложности, большинство пользователей также находят его простым в использовании. Многие пользователи выбирают реализацию reStructuredText и Sphinx, предлагаемую ReadTheDocs, как описано здесь:

Если вашей документации необходимо больше функций, чем предоставляет Sphinx, документация Sphinx описывает, как расширить его функциональность с помощью разработки расширений, хотя эта задача требует компетенции разработчика.

Несмотря на то, что Sphinx наиболее популярен, также доступен другой генератор статических сайтов для restructuredText — Nikolai.

RAML, Swagger и API Blueprint

RAML, Swagger и API Blueprint — похожие методологии описания REST API и используются разработчиками для проверки того, что их разработка корректна. Однако текстовые файлы, используемые этими приложениями для описания API, могут затем использоваться для представления API и справочной документации к нему. В этом простом примере можно воздействовать на каждое существительное.

02

Вы можете увидеть более глубокие примеры с помощью Watson API и их представлений Swagger. Watson — движок искусственного интеллекта, который выигрывает у игроков-людей в Jeopardy, но используется во множестве других контекстов.

Представление Swagger, а также его эквиваленты — не завершённая документация. Они представляют справочную документацию в привлекательном виде, но многим разработчикам нравится работать также с простой текстовой версией. Swagger также не предоставляет уроки, списки сообщений об ошибках и бизнес-контекст, который требуется для полноценной документации API.

Какие документы и контекст необходимо включать?

Документация также должна включать руководства по установке и настройке, если это необходимо, справочную документацию, включая ошибки и исключения, работающие и реалистичные примеры кода и уроки, а также документацию, ориентированную на бизнес, включая записи блога и учебные примеры.

Йогешвор Срикришнан (Yogeshwar Srikrishnan), бизнес-архитектор в Rackspace, замечает, что «Наиболее важная часть опыта для разработчика, который потребляет API — документация для разработчика». В его статье о документировании REST API для Dzone подробно изложены многие важные аспекты документации для разработчиков.

Необходимость хорошей справочной документации — данность, так что давайте начнём с настройки бизнес-контекста. Заманчиво взять то, что предлагает команда маркетинга и использовать это для бизнес-контекста. Но эта информация вряд ли сориентирует вашего пользователя правильно. Дайте пользователю несколько идей о том, как может использоваться API. Если доступны учебные примеры с упоминанием клиентов, это будет полезно упомянуть. Если посмотрите учебные примеры Twitter, то найдёте важную информацию.

Зажигайте пользователей креативно. Например, с API Интернета вещей (IoT) некоторые пользователи думают о путях связи элементов, о которых вы и представить не могли, что они могут работать вместе. Знаете ли вы, что у Roomba есть API и что вы можете использовать это API, чтобы превратить Roomba в музыкальный инструмент?

Если посмотреть на другие наборы документации, то это приведёт к идее о том, что должна включать документация API. Сайт документации PayPal API фокусируется на задачах, которые вы можете сделать с помощью API, описывает, как создать первый REST-запрос, предлагает справочную информацию, предоставляет рабочую панель для приложений, создаёт в онлайне песочницу, доступную каждому, и тому подобное.

Документация Twitter API также всесторонняя и хорошая модель для подражания. Обратите внимание, что многие продукты третьих лиц взаимодействуют с Twitter API, так что вы также можете ознакомиться с документацией к этим продуктам для получения дополнительных идей.

Новый пользователь Twitter API может начать с самого начала — набора ЧаВо.

Установка и настройка

Если ваше API не доступно публично в Сети, вам, скорее всего, потребуется, чтобы пользователь перед использованием API произвёл некоторую установку и настройку. Эту документацию может быть сложно создать, потому что команда разработки может внести множество мелких, но критичных изменений перед тем, как API будет готов. В идеальном случае, вы должны протестировать вашу документацию на нескольких различных конфигурациях, чтобы убедиться, что ваши инструкции корректны. Если ваш пользователь никогда не установит API, он не сможет его использовать. Качественная документация по установке и настройке API — это критически важно.

Делайте обновления API удобными для пользователей

Если вы документируете API, для которых часто отправляются пользователям обновления, актуализация документации может предоставить сложности. Но обновление API тоже может быть сложным для пользователей. Ваша стратегия продукта — решение компании, но в целом сохранение обратной совместимости — весьма желательно. Если вы вынуждены отказаться от старой версии API, отправьте пользователям всю необходимую информацию.

Эджайл-методология также предоставляет хорошие процессы для уверенности в том, что документация актуальна. Если разработана новая функция, ваш процесс должен препятствовать отметке о том, что функция готова, до тех пор, пока не будет документации. Убедитесь, что основная документация имеет понятные контрольные точки для разработки и улучшений.

Выкладывать ли документацию в Интернет

Преимущества размещения документации онлайн, где по ней легко осуществлять поиск — хорошо известны. Но не всегда возможно размещать документацию о продукте в Сети. У вашего руководства могут быть законные причины этого не позволять. Netflix и другие компании приняли решения ограничить рамки доступа к их API отдельными пользователями. Но практически нет сомнений в том, что публичный доступ к вашей документации увеличивает популярность и удобство использование вашего API. Например, пользователь может просматривать документацию на планшете во время прохождения списка шагов. Пользователи могут быть всегда уверены, что у них последний вариант документации. Google по умолчанию индексирует онлайн-документацию, таким образом улучшая поиск таким образом, который сложнее повторить в локальной среде.

Расположение документации онлайн на Github демонстрирует, что ваша компания ищет подходы к пользователям-разработчикам. Вы можете получать прямую обратную связь от разработчиков о том, что корректно и полезно, а что нет. Например, PayPal провёл серьёзную работу над контентом, доступным на Github, включая документацию. И быстрый взгляд на сайт Github, раздел SDK для PayPal для Android показывает, что документы были обновлены семь дней назад (на данный момент).

Тестируйте, тестируйте, тестируйте!

Вам не нужна компетенция разработчика для того, чтобы взаимодействовать с основными разработчиками вашей команды. Однако вы должны знать, как тестировать API, чтобы проверить, что оно работает корректно относительно вашей документации. Если вы можете создать или по крайней мере изменить код примера, который использует API, то этим самым сможете убрать многие препятствия для создания примеров кода, доступных пользователям.

Некоторые обычные инструменты для тестирования REST API включают в себя curl и Postman. Вам может потребоваться помощь вашей команды разработчиков, чтобы заставить их работать у вас, но ваша команда, скорее всего, уже использует эти или похожие инструменты. С помощью curl или Postman вы создаёте запрос, который хотите протестировать, и проверяете, что возвращается корректный ответ. Типичным тестом может быть проверка различных комбинаций параметров, чтобы убедиться, что они работают корректно вместе.

Для других API определите лучший подход для тестирования вашей документации с помощью консультаций с вашей командой разработки. Понятно, что создание точной, работающей документации — высший приоритет для вас, и вам необходимо быть уверенными, что написанное — правильно. Вы не можете заниматься документацией серьёзно, не проверяя свою работу.

В заключение

Если вы хотите документировать API, знайте, что это требует такого же тщательного внимания к деталям, которое требуется и от технического писателя в целом. Вы должны предоставлять и бизнес-контекст высокого уровня, и при этом мало деталей по реализации. Вы можете заявить себя как члена команды разработки и вовлечь всю команду в процесс улучшения документации.

Источник: So You Want to Document APIs …

Тэги: , , , ,

< Вернуться к списку публикаций

Облако тегов