"Разработка документации на программные интерфейсы"....
-
Upload
yandex -
Category
Technology
-
view
2.126 -
download
5
description
Transcript of "Разработка документации на программные интерфейсы"....
![Page 1: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/1.jpg)
1
![Page 2: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/2.jpg)
2
Разработка документации на программные интерфейсы
Светлана Каюшина
![Page 3: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/3.jpg)
3
О чем это я
1. Разработка документации
2. Локализация
3. Примеры в документации
![Page 4: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/4.jpg)
4
Разработка документации
![Page 5: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/5.jpg)
5
Разработчик документации
Раньше сопроводительную документацию писали инженеры
![Page 6: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/6.jpg)
6
Технический писатель
В 90-х годах сложилась профессия технический писатель
![Page 7: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/7.jpg)
7
Я.технический писатель
Технический писатель инженер-разработчик
![Page 8: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/8.jpg)
8
Популяция техписов
" В мире как-то так:
1 техписатель на
20 разработчиков
1
20
![Page 9: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/9.jpg)
9
Наша популяция
" У нас приблизительно так:
1 техписатель на
100 разработчиков
![Page 10: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/10.jpg)
10
Ныряем в разработку
– Консультации с разработчиками – Обсуждения с менеджерами проектов – Мониторинг багтрекера и рассылок – Анализ кода проекта – Функциональное тестирование продукта
![Page 11: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/11.jpg)
11
Выныриваем к читателю
– Работа с продуктом в роли пользователя – Связь с техподдержкой – Отслеживание клубов продукта – Обработка обращений по документации
![Page 12: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/12.jpg)
12
Пишем
Коротко и ясно
![Page 13: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/13.jpg)
13
Как-то так
![Page 14: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/14.jpg)
14
Много API много доки
![Page 15: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/15.jpg)
15
Подгоняем технику
" Все, что можно, вытягиваем автоматом из: – кода, – баз данных, – конфигов, – и других внутренностей продукта
![Page 16: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/16.jpg)
16
Улучшаем код
![Page 17: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/17.jpg)
17
Пример: справочник JS API Карт
![Page 18: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/18.jpg)
18
Тем не менее
Много документации пишем ручками
![Page 19: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/19.jpg)
19
Пример: руководство разработчика
![Page 20: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/20.jpg)
20
Руками сложнее
– Большие объемы – Требуется постоянное обновление – Много перекрестных ссылок – Много заимствований (цитирования) – Различные выходные форматы: HTML и PDF
![Page 21: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/21.jpg)
21
Тяжелая техника
– DITA XML – Редактор Syntext Serna
(сейчас это TechSight/X Editor) – Исходники храним в системе контроля версий – Преобразование через DITA Open Toolkit – Выкладка Debian-пакетами
![Page 22: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/22.jpg)
22
Локализация документации
![Page 23: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/23.jpg)
23
Локализуйте это
" Локализация:
– Языковая – Региональная – Полная = региональная + языковая
![Page 24: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/24.jpg)
24
Кто локализует?
– Локализация = разметка исходников документа – Размечает техписатель
![Page 25: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/25.jpg)
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>
![Page 26: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/26.jpg)
26
Переведите это
– Языковые нюансы и точность перевода – Специальная терминология
![Page 27: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/27.jpg)
27
Кто переводит?
" Переводчик
– носитель языка – лингвист – специалист в области IT
![Page 28: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/28.jpg)
28
Универсал?
![Page 29: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/29.jpg)
29
Do yа speak Turkish?
– Перевод с английского – Независимая оценка качества
перевода
![Page 30: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/30.jpg)
30
Трудности перевода
– Большие объемы – Требуется постоянное обновление – Много перекрестных ссылок – Много заимствований (цитирования)
![Page 31: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/31.jpg)
31
Подгоняем спецтехнику
– XLIFF – Translation Memory – Swordfish – API Яндекс.Перевода
![Page 32: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/32.jpg)
32
Profit
1. Переводим только различия между версиями документа
2. Повторно используем перевод отдельных фрагментов
3. Единый словарь
![Page 33: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/33.jpg)
33
Do it!
![Page 34: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/34.jpg)
34
Что получается: Россия
![Page 35: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/35.jpg)
35
Что получается: Турция
![Page 36: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/36.jpg)
36
Примеры в документации
![Page 37: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/37.jpg)
37
Зачем?
1. Подойдет ли мне?
2. И как этим пользоваться?
3. Хочу попробовать!
![Page 38: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/38.jpg)
38
Hello World!
![Page 39: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/39.jpg)
39
Примеры посложнее
![Page 40: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/40.jpg)
40
Примеряя API
API = данные + инструменты (методы)
![Page 41: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/41.jpg)
41
Оживляем примеры. JS-песочница
![Page 42: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/42.jpg)
42
Мир HTTP API
REST 69%
SOAP 22%
JavaScript 5%
XML-RPC 2%
По данным сайта programmableweb.com от 17.09.2013
![Page 43: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/43.jpg)
43
HTTP API
– Отправить запрос – Получить ответ
![Page 44: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/44.jpg)
44
Сейчас у нас справочники с примерами
![Page 45: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/45.jpg)
45
Песчаный карьер
Нужна спецтехника
![Page 46: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/46.jpg)
46
Готовые решения
www.mashery.com github.com/mashery/iodocs
www.mashape.com apiary.io …
![Page 47: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/47.jpg)
47
I/O Docs
![Page 48: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/48.jpg)
48
I/O Docs: описание операции
![Page 49: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/49.jpg)
49
I/O Docs: ответ
![Page 50: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/50.jpg)
50
Что нам не нравится
" Всё в конфиге:
– Изменение описания = перезапуск приложения – Неудобно набирать длинные тексты в JSON – Никаких DITA-вкусностей (заимствований и др.) – Трудно автоматизировать локализацию JSON
![Page 51: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/51.jpg)
51
Конфиг I/O Docs
![Page 52: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/52.jpg)
52
Хотим лучше и проще
– Зачем нам дублирующиеся сущности: справочник и песочница? – Хотим нормально оформлять – Хотим удобно набирать – Хотим быстро переводить – Зачем нам «чужая» интерфейсная часть?
![Page 53: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/53.jpg)
53
Запилим своё
![Page 54: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/54.jpg)
54
Как мы набираем: Serna
![Page 55: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/55.jpg)
55
Что у нас получается: справочник
![Page 56: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/56.jpg)
56
А вот песочница I/O Docs
![Page 57: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/57.jpg)
57
МОЖНО ПРОСТО ТАК ВЗЯТЬ И
![Page 58: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/58.jpg)
58
Добавить немного магии
{“magic”: “restbox”, …}
![Page 59: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/59.jpg)
59
И справочник превращается
![Page 60: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/60.jpg)
60
Песочница
![Page 61: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/61.jpg)
61
![Page 62: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/62.jpg)
62
Считаем зайцев
" Делаем документ как раньше = делаем песочницу
" Документация ожила = пользователям хорошо
![Page 63: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/63.jpg)
63
Я заканчиваю
![Page 64: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/64.jpg)
64
Наши рецепты
1. Техписатель разработчик, глубоко погружен в тему, умеет писать 2. Переводчик носитель языка, специалист 3. Специальные инструменты документирования и локализации 4. Автоматизация всего, что можно 5. «Живые» примеры
![Page 65: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/65.jpg)
65
Спасибо за внимание
![Page 66: "Разработка документации на программные интерфейсы". Светлана Каюшина, Яндекс](https://reader031.fdocuments.net/reader031/viewer/2022013115/557c6f58d8b42a494c8b45c0/html5/thumbnails/66.jpg)
66
Светлана Каюшина Руководитель службы
8 (495) 737 00 00
[email protected] [email protected]
разработки технической документации
© ООО «Яндекс», 2013