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

Расшифровка

Я действительно живой пример. И когда я сейчас слушала Кирилла, я думала о том, где же вот моя точечка на этих графиках. Я родилась в 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. И на такую задачу можно взять человека без опыта разработки. Он обязательно согласится программировать, а потом втянется и у вас будет хороший специалист на руках. Или на шее. Ну, как посмотреть.

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