1

2

Разработка документации на программные интерфейсы

Светлана Каюшина

3

О чем это я

1.  Разработка документации

2.  Локализация

3.  Примеры в документации

4

Разработка документации

5

Разработчик документации

Раньше сопроводительную документацию писали инженеры

6

Технический писатель

В 90-х годах сложилась профессия технический писатель

7

Я.технический писатель

Технический писатель инженер-разработчик

8

Популяция техписов

"  В мире как-то так:

1 техписатель на

20 разработчиков

1  

20  

9

Наша популяция

"  У нас приблизительно так:

1 техписатель на

100 разработчиков

10

Ныряем в разработку

–  Консультации с разработчиками –  Обсуждения с менеджерами проектов –  Мониторинг багтрекера и рассылок –  Анализ кода проекта –  Функциональное тестирование продукта

11

Выныриваем к читателю

–  Работа с продуктом в роли пользователя –  Связь с техподдержкой –  Отслеживание клубов продукта –  Обработка обращений по документации

12

Пишем

Коротко и ясно

13

Как-то так

14

Много API много доки

15

Подгоняем технику

"  Все, что можно, вытягиваем автоматом из: –  кода, –  баз данных, –  конфигов, –  и других внутренностей продукта

16

Улучшаем код

17

Пример: справочник JS API Карт

18

Тем не менее

Много документации пишем ручками

19

Пример: руководство разработчика

20

Руками сложнее

–  Большие объемы –  Требуется постоянное обновление –  Много перекрестных ссылок –  Много заимствований (цитирования) –  Различные выходные форматы: HTML и PDF

21

Тяжелая техника

–  DITA XML –  Редактор Syntext Serna

(сейчас это TechSight/X Editor) –  Исходники храним в системе контроля версий –  Преобразование через DITA Open Toolkit –  Выкладка Debian-пакетами

22

Локализация документации

23

Локализуйте это

"  Локализация:

–  Языковая –  Региональная –  Полная = региональная + языковая

24

Кто локализует?

–  Локализация = разметка исходников документа –  Размечает техписатель

25

Размечаем исходники

<p><xref locale="ru com" href="http://yandex.ru/yandsearch?text="> <b>Страница результатов поиска Яндекса</b></xref> <xref locale="ua" href="http://yandex.ua/yandsearch?text="> <b>Страница результатов поиска Яндекса</b></xref> — объявления показываются либо над результатами поиска, либо под ними в ответ на поисковый запрос пользователя.</p> <p locale="ru ua com"><xref locale="ru-ru ru-ua ru-com“ href="http://help.yandex.ru/direct/?id=990409"> <b>Рекламная сеть Яндекса</b></xref>— объявления показываются на страницах качественных и посещаемых сайтов Рунета.</p>

26

Переведите это

–  Языковые нюансы и точность перевода –  Специальная терминология

27

Кто переводит?

"  Переводчик

–  носитель языка –  лингвист –  специалист в области IT

28

Универсал?

29

Do yа speak Turkish?

–  Перевод с английского –  Независимая оценка качества

перевода

30

Трудности перевода

–  Большие объемы –  Требуется постоянное обновление –  Много перекрестных ссылок –  Много заимствований (цитирования)

31

Подгоняем спецтехнику

–  XLIFF –  Translation Memory –  Swordfish –  API Яндекс.Перевода

32

Profit

1.  Переводим только различия между версиями документа

2.  Повторно используем перевод отдельных фрагментов

3.  Единый словарь

33

Do it!

34

Что получается: Россия

35

Что получается: Турция

36

Примеры в документации

37

Зачем?

1.  Подойдет ли мне?

2.  И как этим пользоваться?

3.  Хочу попробовать!

38

Hello World!

39

Примеры посложнее

40

Примеряя API

API = данные + инструменты (методы)

41

Оживляем примеры. JS-песочница

42

Мир HTTP API

REST 69%

SOAP 22%

JavaScript 5%

XML-RPC 2%

По  данным  сайта  programmableweb.com  от  17.09.2013  

43

HTTP API

–  Отправить запрос –  Получить ответ

44

Сейчас у нас справочники с примерами

45

Песчаный карьер

Нужна спецтехника

46

Готовые решения

www.mashery.com github.com/mashery/iodocs

www.mashape.com apiary.io …

47

I/O Docs

48

I/O Docs: описание операции

49

I/O Docs: ответ

50

Что нам не нравится

"  Всё в конфиге:

–  Изменение описания = перезапуск приложения –  Неудобно набирать длинные тексты в JSON –  Никаких DITA-вкусностей (заимствований и др.) –  Трудно автоматизировать локализацию JSON

51

Конфиг I/O Docs

52

Хотим лучше и проще

–  Зачем нам дублирующиеся сущности: справочник и песочница? –  Хотим нормально оформлять –  Хотим удобно набирать –  Хотим быстро переводить –  Зачем нам «чужая» интерфейсная часть?

53

Запилим своё

54

Как мы набираем: Serna

55

Что у нас получается: справочник

56

А вот песочница I/O Docs

57

МОЖНО ПРОСТО ТАК ВЗЯТЬ И

58

Добавить немного магии

{“magic”: “restbox”, …}

59

И справочник превращается

60

Песочница

61

62

Считаем зайцев

"  Делаем документ как раньше = делаем песочницу

"  Документация ожила = пользователям хорошо

63

Я заканчиваю

64

Наши рецепты

1.  Техписатель разработчик, глубоко погружен в тему, умеет писать 2.  Переводчик носитель языка, специалист 3.  Специальные инструменты документирования и локализации 4.  Автоматизация всего, что можно 5.  «Живые» примеры

65

Спасибо за внимание

66

Светлана Каюшина Руководитель службы

8 (495) 737 00 00

kaushina@yandex-team.ru yandex-techdoc@yandex-team.ru

разработки технической документации

© ООО «Яндекс», 2013