Клуб технических писателей

Документировать API начать как

Арина
24 апреля 2015, 17:28

Продолжаем серию публикаций с тезисами выступлений гипербатоновцев 2014 года.

На этот раз давайте вспомним доклад Как начать документировать API с прошлогоднего московского Гипербатона.

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

План погружения

1. Изучаем системы контроля версий

SVN, GIT.

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

2. Пробуем среды разработки (IDE)

Для JavaScript API: WebStorm.

Для Java, Objective-C: Intellij IDEA, Android Studio, Xcode.

Достаточно уметь создавать программы класса Hello, world! Сделать самые простые примеры использования API.

3. Подучиваем языки программирования

JavaScript, Java, Objective-C (зависит от API).

Уметь читать код «с листа».

4. Осваиваем генераторы документации из кода

Для JavaScript API: JSDoc.

Для Java, Objective-C: Doxygen.

Выбрать генератор документации из кода и научиться с ним работать.

5. Пишем

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

А пока можно прочитать полную расшифровку записи выступления (под катом, сделано с применением мобильного приложения Яндекс.Диктовка).

Расшифровка

Я действительно живой пример. И когда я сейчас слушала Кирилла, я думала о том, где же вот моя точечка на этих графиках. Я родилась в 81 году. У меня инженерное образование, я работаю в Яндексе техническим писателем, в группе документированиия программных интерфейсов

Тема моего доклада — как начать документировать API.

Как документировать api я сегодня вам расскажу на своем примере. Я пришла в Яндекс, как уже сказала Света, недавно и как раз чтобы в 1 раз в жизни столкнуться с этой задачей. И сейчас я вам расскажу о своем опыте.

Если вы подумываете начать документировать программные интерфейсы, то вы узнаете как действительно начать. А если вы может быть ищете такого документатора, который мог бы выполнять такой задачу, вы  узнаете, что ему предстоит. Итак, давайте начнем.

Application programming interface называют это американцы. У нас говорят апИ или Апи. API — это интерфейс, который позволяет разработчикам использовать функционал некого программного продукта в своих разработках. Ну например, я хочу использовать Яндекс.Карту на своем сайте, — использую API Яндекс.Карт. У Вконтакте есть APIНа самом деле, API очень много и они разные. Документировать API означает описывать то, что сделали одни разработчики для других разработчиков. Для этого нужно глубокое погружение в технологии. Нужно быть специалистом одновременно и в области документирования. И в области разработки.

Кто может быть таким человеком?

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

 Когда я готовилась к докладу, я нашла пример такого человека. Это Линдсей Скотт, модель victoria secret, которая создает приложения для айфона. В принципе её можно уговорить стать техническим писателем. Тем более как она говорит в интервью в колледже у нее еще есть курс русской литературы. Но такой кандидат это скорее исключение, чем правило. И вы слышали об этом сегодня говорил Кирилл.

 Вот у нас всего 2 примера: Линдси Скотт и Кирилл, у которого филологическое образование. Что же делать?

Третий вариант ответа на вопрос кто — это технический писатель без опыта разработки и без опыта документирования таких сложных программных продуктов, которому только нужно помочь погрузиться в технологии, чтобы он мог документировать api. Кто не узнал. На фотографии — это я до прихода в Яндекс. Такой веселый человек. Документировала я только пользовательские интерфейсы. И 5 месяцев назад я пришла в Яндекс. И сейчас я вам отвечу на главный вопрос, который всех интересует.

Как документировать API?

Это очень просто. Надо взять непонятный API и превратить его в понятный API. Правда, вот под знаком вопроса там есть некоторые сложности.

Что для этого нужно сделать?

Нужно сначала самому разобраться. А потом задокументировать API так, чтобы он стал понятен и другим разработчикам тоже. Итак, главный секрет я вам сообщила. А теперь давайте посмотрим, как это выглядело на практике.

Итак, API который мне достался, позволяет размещать карты в мобильных приложениях. Физически это библиотека на языках java и objective c. Платформы ios и android. И как же я начала с этим всем разбираться.

Мой 1 подход к снаряду выглядел следующим образом: операционные системы.

Для начала меня заставили погрузиться в особенности работы с Unix-подобными системами. Дело в том, что Android и iOS это Unix-подобные операционные системы, Mac OS тоже. А я до этого только Windows использовала. Итак, мне выдали Mac для работы и чуть позже выдали справочник с командами операционной системы Linux, которые я изучала.

Мне, конечно, помогали. Вот руководитель группы на фотке (справа). Он выписал мне команды на листочек, основные, которые я потом выполняла в консоли на скорость. Когда я немного уже освоилась с работой на Маке, с операционной системой, можно было переходить ко второму этапу.

Меня познакомили с технологиями документирования, которые используются в Яндексе.

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

Первое, что я узнала (что находится в этом кружке) — это система контроля версий. Код нужно где-то хранить, потом откуда-то взять, документацию нужно где-то хранить (часто для этого используются системы контроля версий).

Служба документирования в Яндексе использует Subversion или SVN. А разработчики на моем проекте использовали GIT. Когда я научилась работать с системами контроля версий, мне рассказали, что документирование в Яндексе строится по принципу единого источника. В двух словах для меня это выглядело так: документы создаются не в Ворде, который я использовала до этого всё время, а в xml-редакторе с поддержкой DITA.

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

То есть я понимала что у меня будет некий код, который надо описать, а потом из моего описания получится документация. Но было непонятно. И тогда я получила свой главный совет, который был записан на этом листочке с объяснениями про системы контроля версий. Не бояться. И после того как я «узбогоилась», можно было действительно переходить к третьему этапу.

Это третья часть моей истории. API.

2 библиотеки, на двух языках, как начинать в этом разбираться?

Мы решили что лучше всего будет начать с примеров использования API и я установила себе среды разработки. Вы сейчас на экране видите логотипы вещей которые я использовала, это Xcode, Intellij IDEA, Android Studio немножко. И попыталась начать писать Хеллоу-ворлды (программы класса Hello, world!). Вот сейчас на экране самый мой популярный запрос в Яндексе в то время: Hello world Android.

Итак, нужно было еще параллельно, конечно, изучать языки. У меня конечно был курс C++ в институте, но это было 10 лет назад и надо было начинать с нуля. Я пошла в библиотеку Яндекса. Сейчас на фотографии вы её видите, взяла несколько книжек. И, вооружившись всем этим, я написала несколько базовых примеров использования нашего API. Конечно, у меня был один пример от разработчиков, вот я с помощью этого примера разобралась в базовых классах и могла уже написать собственное приложение. Оно было простейшее, карта там, несколько меток, но я его сделала.

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

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

И вот тут я поняла, что справочник нужно будет не только один раз сформировать, но и поддерживать. То есть обновлять его каждый раз, как только разработчики внесут изменения в код. Мы оценили объем задачи и получалось, что справочники по двум библиотекам тянут на несколько сотен страниц. В этот момент я создала вот такую вот картинку — как перестать беспокоиться и начать паниковать. Потому что опять стало страшно. Что с этим всем делать было непонятно. Но приступ паники мы быстро купировали и об этом сейчас будет четвертая часть моей истории.

Генерация документации из кода. Конечно, справочники такого объема редко создаются вручную. Часто используются специальные программы, генераторы, которые из кода, снабженного документационными комментариями, могут создавать справочники на человеческом языке. Задача эта не новая и в Википедии я нашла табличку со списком из 54 генераторов, которые все вместе охватывают 24 языка программирования. У нас было всего 2 языка: Java и Objective-C.     

Но нам нужен был 1 генератор для них. Мы попробовали, подумали про несколько генераторов, попробовали JavaDoc, который является классическим инструментом для Java, посмотрели HeaderDoc, который часто используется для Objective-C. В итоге мы выбрали Doxygen.

Doxygen мы выбрали по трем причинам. Во-первых он хорошо справляется с языками семейства C и с Java и на самом деле с большим количеством языков. Во-вторых Doxygen довольно гибкий инструмент. У него большое количество настроечных параметров. И третья причина — xml-выход Доксиджена мы могли сравнительно легко преобразовать в нашу Диту. Дело в том, что у большинства автогенераторов основным выходом является html. С этим было бы сложно работать. И мы выбрали Doxygen. Но нам пришлось написать программу, которая преобразует выход Doxygen в нашу DITA.

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

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

Итак, 4 подхода к снаряду у меня было. На большее количество подходов к снаряду меня не хватило, потому что всё оставшееся время я потратила на следующий слайд. Это типовой комплект документации. Про быстрый старт я вам рассказала, про справочник мы поговорили и осталось руководство пользователя. Вот которым я сейчас занимаюсь. Руководство пользователя это полное описание того, как использовать API, с большим количеством примеров, как правило. И здесь еще примеры вынесены в отдельный пункт, потому что часто их действительно выносят в отдельный документ. У нас есть такая история, например, Песочница, и про это вы можете спросить у Миронова Алексея, кстати, на стендах. Итак, это комплект документации. Давайте в завершении кратко повторю что же пришлось освоить, чтобы к этому комплекту подобраться.

Итак. Начали мы погружение с операционных систем. Продолжили средствами разработки.  Системы контроля версий. Языки программирования. Среды разработки. Генераторы документации из кода. Вот такой путь примерно. На самом деле этот путь не уникален. [вырезано немножко]

А закончить я хочу вот чем. Это мое субъективное мнение. Отличие пользовательских интерфейсов от программных. Когда пользователь начинает пользоваться какой-то программкой, он что говорит?  Все плохо спроектировано. Интерфейс не интуитивный. В последнюю очередь человек жалуется на документацию. Чаще всего потому, что документацию он не читал. Ну бывает, конечно, потому что документация хорошая. 

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

На этом моя история заканчивается.

 

Посмотреть видео доклада 

Скачать презентацию в формате pdf 

2 комментария
Подписаться на комментарии к посту

Собралась с мыслями поделиться своей историей на ту же тему.

Как когда-то говорили на одном из Гипербатонов - у технических писателей очень разные образовательно-карьерные траектории, кто-то - пищущие "айтишники" и инженеры, а кто-то подкованные технически или заинтересованные гуманитарии.

Я гуманитарий, по образованию, складу ума и стилю жизни. Но всегда интересовалась техническими знаниями, программированием и сферой ИТ. Даже диплом и научные работы у меня были и есть на смежную тематику информационных технологий и политики, коммуникации.

В определенный момент меня пригласили поработать в крупную ИТ-компанию в Самаре контент-менеджером, который бы писал полный цикл текстов - истории внедрений продукта, описания, release notes, презентации, наполнял бы блог, писал статьи на Хабр и т..д Спустя примерно полгода мы решили попробовать и другую область - написание документации на продукт, сначала - пользовательской и админской (мануал по инсталированию и настройке), поскольку документация - такое же текстовое лицо компании, как и другие. Получалось на мой взгляд неплохо, за этот период удалось создать хороший комплект документации, включая встроенную справку.Мы работали на редакторе Serna в формате Docbook 5. И это позволяло конвертровать документацию сразу в html  и pdf, просто редактируя стили в CSS. Параллельно я училась работать с собственным фреймворком компании, изучала код на Java, помогала в тестировании.

Ключевые навыки, приобретенные на данном этапе - это знание продукта и бизнес-логики, процесса разработки программного обеспечения в целом, работа с SVN и системами сборки, умение читать код, работа с IDE. Параллельно онлайн изучала Python, пробовала немного писать на нем, какие-то простые скрипты для чтения и парсинга тестовых файлов, например.Ключевой момент - если пытаетесь что-то изучать, пробуйте сразу применять это для упрощения своей работы. То есть если писать скрипт, то чтобы можно было им пльзоваться. Подумайте, какую рутинную ежедневную работу можно автоматизировать.

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

На этой стадии мне пришлось научиться читать другой язык программирования - Lua, но после Java он оказался гораздо проще. Сменить систему контроля версий оказалось легко, они в целом устроены похоже.

Понадобились ранее не нужные навыки в SQL  и работе с СУБД, а также знание основ автотестирования, в прежнем компании тестирование было ручное, но здесь мне надо было только уметь читать тесты.

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

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

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

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

Привет. А проект Диктовка закрыли? Ссылка https://mobile.yandex.ru/apps/dictation/android/ ведёт на 404 страницу :(