Семь навыков, которые необходимо учитывать при найме технического писателя для документирования API… или может быть стоит обратить внимание на что-то ещё?
1. Навыки UI/UX разработки и применяемые технологии технического писателя API
Как технические писатели API они не просто обладают опытом в сфере UI/UX-разработки, но и понимают исключительное восприятие пользователя.
Не так много технических писателей вникают в алгоритм взаимодействия с пользователем. Хотя вряд ли их можно винить в этом. Наша индустрия развивается с очень высокой скоростью со стороны разработчиков. Эти последствия отразились в документации.
Многие технические писатели не до конца понимают, что весь Интернет — это один большой API-интерфейс. Главным образом они подключают сервисы благодаря REST-архитектуре (хотя финансовые учреждения полагаются на протокол SOAP в течение десятилетий). На момент написания этой статьи существовало около 30 000 открытых API. По оценкам отраслевых экспертов, закрытых в четыре раза больше.
Высококвалифицированные кандидаты на должность технических писателей API имеют большой опыт в создании пользовательских интерфейсов (по крайней мере должны). Будь то посредством WordPress или иной CMS-системы, они понимают основные принципы управления онлайн-контентом.
В некоторых компаниях не приемлют, чтобы технические писатели копались в базе исходного кода. Очевидно это предусмотрено для того, чтобы уменьшить риски. Однако проблема, с которой сталкиваются многие организации, заключается в балансе между исходными API материалами и тем, как они представлены конечным пользователям.
Если в вашей команде уже присутствуют разработчики контента, включите их в процесс тестирования продукта. Это часть протокола SDLC, который предоставит им обширную информацию о версиях пользовательского интерфейса. Я работал с техническими писателями по документированию, которые смогли улучшить свои навыки, применивших тестирование на удобство использования как часть своей работы в создании лучшего продукта.
Прежде чем мы продолжим, мы должны продемонстрировать разницу между хорошим и плохим API-ресурсом. Они бывают разных видов.
Нанять технического писателя API – это вам не в парк сходить. По правде говоря, я проводил собеседование с многими из них, и часто их навыки варьировались.
Типичные проблемы при найме технических писателей API:
- Традиционные навыки технического писания не соответствуют новым стандартам
- Кадровики одобряют кандидатов на должность технических писателей API, которые имеют ограниченный опыт
- Технические писатели противятся отсеиванию примеров кода с написанием API запросов и ответов
- Существует не так много программ по обучению документированию для технических писателей, чтобы ознакомить их с API
- Применяемые технологии развиваются слишком быстро на стороне разработчиков, превосходя навыки технического писателя документации.
PDF документы не для технических писателей API
Кандидаты на должность технического писателя API промышленного профиля склонны к использованию выходных документов в формате PDF. Забудьте о PDF документации. Это старо как мир, и вот почему…
Проблема их применения влияет на удобство использования. Создание справочных руководств для конечных пользователей — далеко не сложная операция на мозге.
Но при этом недостающим компонентом является разработка пользовательского интерфейса, который отображает API запросы и ответы с примерами кода. Также сюда можно отнести документирование механики конечных показателей и параметров наряду с привязками кода.
Традиционно этот процесс осуществлялся с использованием подробной структуры. Вы уже знакомы с множеством длинных PDF-файлов с бесконечной прокруткой.
Например, крупная финансовая компания, с которой я консультировался, застряла в каменном веке. Как ни странно, но их технический писатель API документировал исходный код в документах Microsoft Word. Затем конвертировал их в те самые растянутые PDF-файлы.
Это большая ошибка.
Почему не PDF-файлы?
Конечным пользователям (разработчикам) требуются ресурсы быстрой интеграции. Просматривать 346-страничный PDF-документ — пустая трата их времени. Но это еще не самое плохое.
- Что происходит, когда вы меняете лог обновлений?
- Должны ли разработчики пренебрегать старыми версиями ваших PDF-файлов?
- Какой PDF-файл будет подходящим для них при поиске справочной информации?
Не забывайте, что помощь в подключении к вашему API приравнивается к удовлетворению клиентов. А значит и к прибыли. Так почему же так много команд технических писателей API полагаются на устаревшие инструменты разработки?
Обычно это из-за плохих рекомендаций, предлагаемых разработчиками или DevOps-методиками. Они пытаются разработать решение, которое соответствует их команде разработчиков.
Чаще всего они приходят к использованию PDF-документации.
Быстро, легко и наверняка. Тем не менее, они не являются ни явными, ни удобными для пользователя. Написание простых в использовании API интерфейсов является основой для поддержания максимальной эффективности системы интеграции клиентов.
2. Сильные качества технического писателя API
Самым важным навыком является надежная защита онлайн-документации пользователей.
Еще в 2007 году онлайн справочными ресурсами были «MIA». Даже такие компании, как «Apple», по-прежнему полагались на создание множества руководств. Те дни уже прошли.
Я работал с несколькими предприимчивыми членами команды, которые ушли от старомодного форматирования к новому массиву документирования в техническом писании API. Здесь необходим устойчивый интерес для отказа от формальных структур.
Признайте это. Многие из нас выросли на печатных материалах. Помните эти тонны изданий Encyclopedia Britannica, которые мы шерстили в поисках информации? Ну, это конечно относится к тем из нас, кому уже за 30.
Страсть является средством для прыжка.
Еще в 2009 году я увидел такую возможность в своей карьере. Заинтересовавшись обращением своей страсти к техническому писанию в управление онлайн-документацией, я занялся этим всерьёз. По началу все ограничивалось CMS управлением справочной документацией.
В 2012 году я заметил, что наиболее распространенной была тенденция использования статических страниц. Компании больше не полагались на громоздкую и сложную архитектуру баз данных веб-сайтов для своих справочных руководств по API.
Но проблема заключалась в том, что технические писатели не улавливали суть…
Уход от качественных ограничений MS Word это не то, что они рассматривают в изучении технического писания. Как раз наоборот. Также некоторые писатели не считают себя технически грамотными.
Некоторые хвастаются преимуществами экспорта документов Word в чистые HTML. Это неплохая идея. Вряд ли это будет практичным при создании динамической API документации.
Причинами проблем всегда остаются вопросы форматирования и CSS. MS Word предлагает ограниченную архитектуру. Так что громоздкий рабочий процесс не подходит для упрощенной миграции контента в пользовательский интерфейс.
Документация API, отвечающая мировым стандартам, должна представлять собой комплекс справочных ресурсов в сочетании с динамическим пользовательским интерфейсом.
Я говорю вам правду, утверждая, что эти типы интерфейсов предназначены для максимального удобства в использовании. Слишком много компаний рассматривают API документацию в качестве дополнительной задачи в своем протоколе SDLC.
Частыми причинами являются:
- Неэффективное планирование
- Отсутствие наблюдения за конечными пользователями
- Сжатые сроки на выпуск новых API-интерфейсов
- Нехватка квалифицированных кандидатов на должность технических писателей API для работы с исходным кодом
Техническое писание API документации должно планироваться на ранних стадиях проекта.
3. Опыт разработки клиентской части
Лучшие технические писатели API имеют опыт программирования. Особенно с использованием таких инструментов, как:
- CSS | HTML
- JIRA | Perforce
- Middleman | Unix
- GitHub | Bitbucket
- Swagger | Postman
- Ruby | Slate | Markdown
- Программирование посредством командной строки
Почему эти навыки программиста считаются эталонными?
Зачастую программисты хороши в создании и тестировании фреймворков для API. Немногие могут устранить пробел между конечными показателями и написанием пользовательской справки, связанной с ними.
Это общая проблема в организациях любого размера. Мой подход заключается в том, чтобы сократить задержки, создав пользовательский интерфейс самостоятельно.
Я работал с несколькими крупными финансовыми учреждениями, управляющими и разрабатывающими API документацию по пользовательскому интерфейсу. Обычно это закрытые API. Ограждение своих руководств по интеграции от общего доступа ограничивает использование Swagger или Github для размещения собственных API-материалов.
Если вы дочитали до этого момента, я имею в виду статические страницы, разработанные с использованием Ruby | Slate | Markdown.
Абсолютно простые примеры API документов
Зачем обновлять ваши API документацию?
Ваши конечные пользователи отчаянно нуждаются в ясности.
Скорее всего, вы слышали от клиентов или пользователей вашего продукта жалобы на ваши текущие API ресурсы. Если так, то добро пожаловать в клуб.
Каждый месяц со мной связываются отчаянные руководители проектов, готовые обновить их справочный контент по интеграции API.
Их жалоба № 1 заключается в том, что их технические писатели не понимают документацию без содержания справочной информации. Если вы не разбираетесь в собственных API ресурсах, есть две части:
- Справочные документы, которые документируют такие элементы, как примеры кода, классы, конечные результаты и ответы
- Несправочные материалы предоставляют вводную справку по вашему API вместе с основанными на описании задачах пошаговыми инструкциями по интеграции
Написание API документации является одним из самых востребованных навыков в индустрии информационных технологий. Особенно для поставщиков продуктов и услуг с миллионной клиентской базой.
4. Способность к управлению проектами
Лучшие из технических писателей API обладают опытом работы с инструментами управления проектами.
Будь то системы JIRA или Perforce, они должны следить за ходом спринта. Это дает им возможность подключаться к рабочему процессу по протоколу SDLC.
Я работал над несколькими проектами, где технические писатели не были включены в собрания по управлению проектами. Руководитель проекта заявлял, что роль технического писателя не была существенной в создании продукта. Что ж, если она не существенна, то, что же тогда? Каждый этап разработки продукта и интеграции API должен быть хорошо знаком для ваших технических писателей.
Следствием отстранения команд технических писателей API от разработки продукта является недостаток знаний о продукте. Слишком много технических писателей обходят подключение вашего бэк-энда, ожидая перехода от тематики к проекту. Это противоречит созданию простой и понятной документации для конечного пользователя.
С другой стороны, я руководил проектами, где технические писатели должны были интегрировать свои проекты по техническому писанию в JIRA. В этих случаях у нас были тысячи требований. Таким образом, управление бесконечным потоком документации по данным пунктам лучше всего было выполнять в соответствии с теми же процессами, которые используют разработчики для отслеживания прогресса в спринте.
Технические писатели API военно-направленного профиля должны быть вовлечены во все аспекты управления проектами.
5. Полное понимание структуры
Это важная черта. Например, что если у вас есть мощный API ресурс, такой как Twillio.com? Их документация оказывает поддержку для следующих ресурсов: (рисунок)
Как видите, API-документация на Twillio предоставляет блестяще структурированную среду. Не удивительно, что они доминируют в индустрии коммуникаций.
Внимание!
Опытным техническим писателям не нужно полностью управлять таким типом архитектуры пользовательского интерфейса. Однако им необходимо хорошо разбираться в инструментах бэк-энда, которые размещают такие типы полноценных API документов.
Вот почему важно наличие по крайней мере 5 лет опыта работы в сфере разработки пользовательских интерфейсов.
6. Гибкость
Последняя черта, которую я считаю необходимой, — это энтузиазм в гибкости. Я участвовал в работе с командами, где была очевидная необходимость привлечения технических писателей для тестирования продукта. Некоторые команды игнорируют такие кажры, но, как у технических писателей, у нас, безусловно, есть время.
По-настоящему заинтересованные технические писатели должны быть готовы вплотную заняться тестированием продукта по двум причинам:
- Повлиять на будущие функциональные возможности
- Стать ценным участником команды разработчиков
На данном рынке наем за один набор отработанных навыков довольно распространен. Тем не менее, это дорогого стоит.
7. Креативность в вариантах исполнения
Swagger UI
Размещение ваших API документов часто может быть как простым, так и сложным. Большинство разработчиков не хотят иметь ничего общего с процессом размещения. По крайней мере, если это связано с настройкой пользовательского интерфейса.
Swagger UI — хороший ресурс, если вы ищете стороннее решение. Я работал в нескольких командах, где Swagger UI являлся простым и очевидным решением. Главным образом для преимуществ автоматизации создания открытой API документации.
Проблема возникает тогда, когда вы хотите интегрировать трехколоночный формат (прочитайте, почему вы должны) вместе с фирменными стилями вашей компании. Одним из проектов, в которым я участвовал, был API-интерфейс для частного банковского обслуживания. Технология Swagger не предлагала варианты настройки, необходимые для обслуживания своих конечных пользователей.
Еще одной проблемой для моего клиента была необходимость в подробном описании API-ответов. Интерфейс Swagger не предлагает неограниченные поля для описания. Мой опыт показывает, что, несмотря на быстрое создание документов, Swagger в основном полагается на растянутую форму прокрутки пользовательского интерфейса.
Так почему же так много команд разработчиков программного обеспечения используют Swagger? Это быстрое решение целого комплекса требований. Но что, если вы хотите обслужить своих конечных пользователей с помощью простых трехколоночных форматов?
Вам понадобится создать специфический пользовательский интерфейс. Я твердо уверен, что индустрия в слишком большой степени полагается на инструменты разработчика для API документации. Это идеально подходит для них. Это не так как с пользователями, которым может понадобиться много рук, чтобы пройти через этапы интеграции.
Readme
Другое автономное решение для пользовательского интерфейса — Readme.io. Ресурс является довольно приличным и универсальным поставщиком документации. Думайте о нем как о подобном WordPress помощнике по API. Задача для многих команд разработчиков заключается в том, что у них, как правило, есть стандарты интеграции, которые обязательны для соблюдения в рамках методик DevOps.
Например, многие финансовые учреждения ограничены в использовании сторонних решений из-за соответствия требованиям PCI. Несмотря на то, что Readme интегрируется с Swagger (в любом случае на этом этапе написания), если ваш API является закрытым, может возникнуть риск. Другая проблема заключается в том, что их уровень настройки пользовательского интерфейса ограничен. Я работал над несколькими корпоративными API проектами, где требовался неограниченный набор настроек для соответствия фирменному стилю.
Помните, что только пользовательский опыт определяет, облегчит ли ваша API документация их жизнь или нет. Работая с разработчиками в течение многих лет, я чувствую, что они слишком крепко привязаны к системам поддержки, подходящим для их команд. Это не критика. На самом деле это является следствием их опыта, основанного на требованиях.
Следовательно, возникает простой вопрос: соблюдение таких требований более важно, чем упрощенный пользовательский интерфейс? Вопрос может оказаться деликатным из-за требования к уравниванию между сроками выпуска и обучения пользователей API-интерфейсов для их быстрого подключения. Но если вы спросите менеджеров по работе с клиентами и руководителей отделов продаж, они расскажут вам реальную историю: «Клиенты не в восторге от нашей справочной документации по API».
Источник: http://www.pdgseo.com/category/api-technical-writer