Технические писатели, способные написать документацию для разработчиков, пользуются большим спросом, особенно в районе Силиконовой долины. Есть много технических писателей, которые могут написать документацию для пользовательских интерфейсов, но не так много тех, кто может ориентироваться в среде разработчиков, чтобы предоставлять высокотехнологичную документацию для разработчиков, работающих с кодом.
На этом курсе уже были вкратце упомянуты вакансии в разделе Рынок документации REST API. Теперь, в этом разделе курса по документации API рассмотрим поближе рынок вакансий для документации API.
Почему работодатели требуют умение читать код
Обеспечение ценности без глубоких технических знаний
Утешения для технических писателей
Переход к роли технического писателя API документации может стать сложной задачей. Работодатели, как правило, предъявляют три требования:
- знание 1-2 языков программирования или других технических основ;
- опыт написания документации для разработчиков;
- портфолио с примерами, демонстрирующими первые два пункта.
Почти в каждом описании вакансий технических писателей документации для разработчиков есть следующие требования:
Возможность читать код на одном или нескольких языках программирования, таких как Java, C ++ или Python.
Какова мотивация этих требований, особенно если основные API-интерфейсы являются RESTful. В конце концов, работодатели не могут требовать от тех.писателя навыков программиста. Нет, но вот самый распространенный сценарий. У компании есть REST API для взаимодействия со своими сервисами. Чтобы упростить разработку, компания предоставляет API-интерфейсы REST для SDK и реализации на разных языках.
Для примера, взглянем на API Algolia. Их API документацию можно посмотреть здесь. Однако, если внедрять Algolia (который предоставляет функцию поиска для сайта), придется следовать документации для конкретной платформы или языка.
Хотя пользователи могут писать свой собственный код при использовании конечных точек REST, большинство разработчиков предпочитают использовать существующий код и копировать то, что им нужно.
Работая в Badgeville, Том Джонсон и его команда разработали коллекцию JavaScript-виджетов, которые разработчики могли легко копировать на свои веб-страницы, внося коррективы по мере необходимости. Разработчики могут создавать свой собственный виджет JavaScript (с нуля) на основе обращений к конечным точкам REST, но иногда бывает сложно узнать, как получить всю нужную информацию, а затем правильно ее обработать на выбранном вами языке. Проще использовать готовые виджеты JavaScript.
Стоит помнить, что разработчики обычно используют REST API в качестве стороннего сервиса. Основной задачей разработчиков является код их собственной компании; они просто используют сторонний REST API в качестве дополнительного сервиса. Таким образом, разработчики хотят просто войти, получить код и выйти. Такой подход «войти-и-выйти» заставляет компании предоставлять несколько клиентских SDK на максимально возможном количестве языков. Такая забота позволяет разработчикам быстро и эффективно внедрять API.
Если нанимать технического писателя для документирования Algolia, какие бы требования к работе были необходимы? Теперь можно понять, почему, несмотря на то, что основная работа включает документирование REST API, было бы хорошо иметь «способность читать код на одном или нескольких языках программирования, таких как Java, C ++ или Python».
Количество SDK, которые компания распространяет, может значительно различаться. У кого-то может не быть шесть SDK на нескольких языках и сред для API. Можно быть в C++ only, где все, что нужно знать, это C++ и ничего более. Если это так, необходимо углубиться в C++, чтобы повысить свою ценность как тех. писателя.
Несмотря на то, что распространение кода и платформ создает требование к знанию многих языков техническим писателем, понимание того, что происходит на одном языке программирования, облегчит описание эталонных реализаций на других языках программирования.
В основном, в разных языках меняются фрагменты кода и некоторые термины. Можно ссылаться на «функции» вместо «классов» и так далее. Тем не менее, все языки может быть проблемой, поэтому так сложно найти технических писателей, которые имеют навыки создания документации для разработчиков, особенно SDK и примеров приложений.
Степень, в которой можно обеспечить ценность своей роли технического писателя, часто прямо пропорциональна уровню технических знаний. Например, получив работу, которая включает в себя работу с несколькими проектами API с использованием незнакомых языков, все равно можно упростить документацию для проектов. Однако, это будет скорее роль редактора / издателя, чем роль писателя.
Во многих высокотехнологичных организациях роль редактора / издателя становится все более распространенной. Инженеры напишут технический материал, особенно справочную документацию, а технические писатели будут уделять больше внимания тому, чтобы контент проверял все флажки - чтобы у него был обзор, примечания к выпуску, решались пользовательские задачи, следовал руководству по стилю, интегрировался с другими документами и так далее. Можно формировать и организовывать контент, а также определять области, в которых он недостаточен или нуждается в расширении, но для того, чтобы повысить свою ценность, требуется более глубокое знание предмета.
Отсутствие дополнительных технических знаний, принижает ценность технического писателя. В статье How API Documentation Fails Мартин Робиллард и Гиас Уддин объясняют это:
Неудивительно, что самыми большими проблемами в документации API были те, которые требуют самого большого технического опыта для решения. Заполнение, уточнение и исправление документации требуют глубоких, авторитетных знаний о реализации API. Это делает выполнение этих задач трудным для тех, кто не является разработчиком или недавно участвовал в проекте.
Без глубоких, авторитетных знаний об API будет сложно заполнять, уточнять и исправлять ошибки в контенте.
Баланс между общими и специализированными ролями - это постоянная проблема, которую рассмотрим в следующей теме Сколько кода нужно знать? Короче говоря, если нужно решить самую большую проблему в документации API, тогда потребуется больше технических знаний в предметной области.
В качестве утешения от этого стресса, связанного с необходимостью знания нескольких программных областей, можно утешиться тем фактом, что API-интерфейсы REST (которые помнят, что они не зависят от языка) становятся все более распространенными и заменяют API-интерфейсы нативных библиотек. Преимущества предоставления универсально доступного API с использованием любой языковой платформы обычно перевешивают особенности, получаемые от API нативной библиотеки.
Например, у компании Параметр 41 был API Java, .NET и C ++ - каждая реализация выполняла одно и то же, но на разных языках. И был SDK для Android и iOS.
Поддержание одной и той же функциональности на трех отдельных платформах API было серьезной проблемой для разработчиков компании. Мало того, что было трудно найти разработчиков с навыками работы на этих трех платформах, так как наличие нескольких баз кода затрудняло тестирование и сопровождение кода. Было в три раза больше объема работ, не говоря уже о трехкратном объеме документации.
Кроме того, поскольку нативные библиотечные API-интерфейсы реализованы локально в коде разработчика, почти невозможно заставить пользователей перейти на последнюю версию API. Приходилось отправлять новые библиотечные файлы и объяснить, как обновить версии, лицензии и код развертывания. Если вы когда-нибудь пытались заставить крупную компанию с длительным процессом развертывания обновлять код, который они разворачивали каждые пару месяцев, вы понимаете, насколько это нецелесообразно. Развертывание простого обновления может занять 6-12 месяцев и более. В течение этого времени компания часто борется с множеством ошибок и другими проблемами, которые отбрасывают их назад.
Для разработки API гораздо более целесообразно перейти к модели SaaS с использованием REST, а затем создать различные клиентские реализации, которые кратко демонстрируют, как вызывать API REST с использованием разных языков. С помощью REST API можно обновить его в любое время (возможно, поддерживая обратную совместимость), и разработчики могут продолжать использовать свой код развертывания.
Тем не менее, одна из областей, в которой API-интерфейсы REST могут вызывать проблемы, - это мобильные устройства (например, смартфоны и планшеты, автомобильные гаджеты, устройства потокового мультимедиа). В этих случаях вызовы API REST имеют тенденцию быть медленными, поэтому вместо них используется API нативной библиотеки (например, Android).
В следующем разделе Сколько кода нужно знать? узнаем, сколько нужно знать кода, и рассмотрим стратегии его изучения.