Разработка документации: от постановки до деплоя

SECR 2018
Екатерина Носкова
Руководитель отдела документирования, Xsolla

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

Для решения задач документирования мы используем генератор статических сайтов Hugo (markdown + Go templates + YAML) и Gitlab CI/CD. Статические страницы документации собираются из шаблонов и публикуются в HTML на 6 языках. Каждый шаблон описывает логику сборки страницы в соответствии с типом контента. Для локализации документации используется подход Continuous localization, который реализован через связку Gitlab CI/CD + Serge + Smartcat.

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

Transcript

1. Разработка документации: от постановки до деплоя Екатерина Носкова Xsolla Software Engineering Conference Russia 2018 October 12-13 Moscow
2. ОБ XSOLLA Xsolla создает решения, которые помогают разработчикам игр выпускать, монетизировать и продвигать свой продукт в любой точке мира. РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
3. ДОКУМЕНТАЦИЯ ДЛЯ РАЗРАБОТЧИКОВ Часть partner journey: • знакомство с продуктами • оценка сложности интеграции • отслеживание изменений Разноплановый контент с разной структурой страниц и специфическими требованиями РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
4. ДОКУМЕНТАЦИЯ ДЛЯ РАЗРАБОТЧИКОВ РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ 6 руководств по интеграции 40+ рецептов интеграции 2 версии справочника API 1 changelog 28 тыс. слов 6 языков }4 техписателя 1 переводчик- копирайтер
5. ТРЕБОВАНИЯ К ДВИЖКУ • переиспользование контента • поддержка интернационализации • легкая масштабируемость (добавление нового контента, новых языков, новых версий API) • кастомизация HTML и CSS • подключение кастомных JS-скриптов и других сервисов • быстрая сборка и быстрое выкладывание • одна платформа для разнопланового контента (в идеале) • публикация только в HTML РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
6. ТЕХНОЛОГИЧЕСКИЙ СТЕК ATOM • SOURCE CODE EDITOR GITLAB • SOURCE CODE REPOSITORY • CI/CD HUGO • STATIC SITE GENERATOR • GO TEMPLATES ENGINE РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
7. ПОЧЕМУ HUGO? • входит в тройку лидеров static site generators (staticgen.com) • быстрый (сборка 300 страниц на одном языке ~ 2,5 с) • поддерживает шаблонизацию и интернационализацию • распространяется под лицензией open-source • гибко кастомизируется • есть компетенции на Go, смогли быстро собрать прототип РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
8. КАК РАБОТАЕТ? • 5 HTML-шаблонов для типовых страниц • контент в MD • ресурсные файлы в YAML • локальная сборка с live reload • деплой по git-тегам через Gitlab CI РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
9. СБОРКА РУКОВОДСТВА РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
10. СБОРКА РУКОВОДСТВА: HTML-ШАБЛОН РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
11. СБОРКА РУКОВОДСТВА: КОНТЕНТ РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
12. СБОРКА РУКОВОДСТВА: РЕСУРСНЫЙ ФАЙЛ РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
13. СБОРКА РУКОВОДСТВА: ДЕПЛОЙ РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
14. ЧТО ЭТО ДАЕТ? • Переиспользование контента • Быстрая загрузка страниц — меньше 3 с для самой тяжеловесной страницы • Быстрый деплой — меньше 2 минут • Легкая масштабируемость РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
15. КАК ЛОКАЛИЗУЕМ? GITLAB • YAML RESOURCE FILES SMARTCAT • COLLABORATION WITH TRANSLATORS • TRANSLATION MEMORY • GLOSSARIES SERGE • CONTINUOUS LOCALIZATION ENGINE РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
16. GIT FLOW РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
17. SERGE-SMARTCAT FLOW РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
18. ЧТО ЭТО ДАЕТ? • Консистентность переводов и терминологии • Оптимизация затрат на локализацию • Переиспользование контента • Легкая масштабируемость РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
19. DOCUMENTATION FLOW РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ 1 2 3 4 5 6 7 Постановка задачи Сбор информации Подготовка контента Сборка контента Локализация контента (5 языков) Тестирование (stage, несколько итераций) Публикация (prod) }2-3 дня } 3-5 дней
20. ПОЛЕЗНЫЕ ССЫЛКИ • staticgen.com • gohugo.io • serge.io • smartcat.ai • LocKit 2018 РАЗРАБОТКА ДОКУМЕНТАЦИИ: ОТ ПОСТАНОВКИ ДО ДЕПЛОЯ
21. Спасибо! e.noskova@xsolla.com