Как стать техническим писателем API

20.06.2014

Мы решили не обойти вниманием в нашем блоге ещё один актуальный вопрос технического писательства – документацию для API. Уже любимая нами Сара Мэддокс, технический писатель API компании Google, снова готова поделиться опытом.

Один мой знакомый технический писатель недавно спросил, если ли у меня советы, как стать техническим писателем API. Это человек, который пишет документацию, ориентированную на разработчика и описывающую программный интерфейс приложения (API), набор средств для разработчиков программного обеспечения (SDK) и другие инструменты, которые разработчики используют, чтобы заставить одно приложение «общаться» с другим. Я могу поделиться некоторыми советами.

В ориентированной на разработчика документации есть три стороны – написание, технологии и «отношение».

Написание

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

Технологии

С технической стороны необходимо знать основы веб-технологий: HTML, CSS и JavaScript. W3Schools предлагает хорошие бесплатные курсы, чтобы вы получили или освежили знания в этой сфере.

Если вы стремитесь работать в конкретной компании, узнайте, какие технологии используют их разработчики, и хорошо их изучите. Также неплохо знать широко используемый язык программирования, такой как Java или C++, и пройти базовый курс программирования, чтобы знать, что это такое.

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

Отношение

Техническийписательобязанлюбить API и SDK. С вашей точки зрения они – центр мироздания. Погружайтесьвпонятия, оперируйтемоднымисловечками. Узнайте, чтоделаюткрутыеребята. Играйтестехнологиями.

Hacker News  – отличный сайт для дискуссий. Регулярно заглядывайте на Hacker News Daily, чтобы понять самые горячие темы. Этот сайт – отличный микс технических тем, всех видов технологий, политических и социальных тем и многого другого. Поначалу технические темы будут вас пугать, но через пару недель вы уже начнёте неплохо разбираться.

Экспериментируйте с API, например, с Google Maps

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

Для примера, попробуйте Google Maps Java Script API. Я отношусь предвзято, ведь я только недавно начала создавать эту документацию 🙂 . Но думаю, неплохо начать именно с этого API. Оно вполне доступно – если вы пользуйтесь GoogleMaps, вы узнаете функции, предлагаемые API. Или вы сможете найти API, просто создав HTMLстраницу в текстовом редакторе и скопировав туда образец JavaScript из инструкции. Очень здорово наблюдать, как рождается ваша собственная карта с полным функционалом GoogleMaps, на основе которых она создана

Ещё советы?

А как насчёт вас? Вы можете что-то посоветовать начинающим писателям API? Я вот хотела придумать, какую бы хорошую книгу посоветовать, но ничего не пришло в голову. Буду рада любым идеям.

Источник: How to become an API technical writer

Тэги: API, опыт, советы