Docs Like Code in Enterprise

Документация как код в промышленных масштабах

Николай Волынкин

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

Docs like Code

  • Что это?
  • Зачем?
  • Как?
_images/plesk_logo.png

Plesk

Hosting control panel

  • 377 000 серверов

  • 11 000 000 сайтов

  • 6% всех сайтов в интернете

    (Исследование от Netcraft, март 2017)

docs.plesk.com

  • 20 руководств (книг, guides)
  • 10 языков
  • Несколько версий продукта
  • 4072 страниц на английском

Author IT (since 2005)

  • WYSIWYG (только Windows)
  • Единый источник (Single source)
  • Хранится в БД
  • Локализация
  • Публикация в HTML (уродливый)

Что не так

  • Нет контроля версий (version control), нет откатов (rollbacks)
  • Ревью по электропочте
  • Нет поддержки для версий продукта
  • Публикация неконтролируемая и вручную

Что мы хотим

  • Контроль версий и откаты
  • Командную работу и процессы
  • Документацию для версий продукта
  • Автоматизированную и контролируемую публикацию
  • Переехать без боли и потерь (не руками)

Неплохо бы

  • Сохранить структуру для SEO
  • Любая ОС
  • Open source
  • Сообщество

Варианты

  • Другая система (authoring system)
  • Wiki
  • Confluence
  • XML-based: DITA, DocBook
  • Документация как код

Документация как код

(Docs like code)

  • Пишем на легковесном языке разметки (lightweight markup language)
  • Обращаемся как с программным кодом

Lightweight Markup Languages

  • Можно прочитать, если напечатать на бумаге
  • Есть структура для обработки машиной

Выбор

  • Markdown
  • reStructuredText
  • AsciiDoc
  • LaTeX

reStructuredText + Sphinx

Python, Mozilla, Ansible, OpenStack,

Plesk

_images/lists-code.png _images/lists-html.png
_images/links-code.png _images/links-html.png
_images/tables-code.png _images/tables-html.png
_images/admonition-code.png _images/admonition-html.png
_images/features-code.png _images/features-html.png
_images/structure-code.png
_images/structure-html.png

Шаблоны

(templates)

Данные + шаблон → данные в нужном представлении

<!DOCTYPE html>
<head>
  {% block htmltitle %}
  <title>{{ title }}</title>
  {% endblock %}
  <!-- ... -->
</head>
<body>
  {% block header %}
  {% include header.html %}
  {% endblock %}
  <!-- ... -->
  {% block footer %}
    {% include footer.html %}
  {% endblock %}
</body>

Темы

(themes)

  • Шаблоны
  • CSS
  • Подключаемая динамика
  • Что угодно ещё

Как получить :

  • командная строка
  • библиотека
  • GUI

~ 5-10 секунд

Форматы:

  • HTML
  • PDF
  • DOCX
  • EPUB
  • Unix manpages
  • …

1. Контроль версий, ветки и откаты

Git!

Diffability

git diff

Blameability

git blame

Общий репозиторий с продуктом?

Нет: книга ←→ сценарий и роль, не продукт

Общий репозиторий на всю документацию??

1 книга ←→ 1 репозиторий

2. Совместная работа и процессы

Стабильные ветки Git

(Stable Git branches)

После ревью и приёмки.

Рабочие ветки (Feature branches)

Текущая работа (work in progress).

Одна задача ←→ одна фичеветка

Pull (merge) request

feature → master

Team workflow

3. Версии продукта

Разные стабильные ветки

4.1. Автоматизированная публикация

Сервер непрерывной интеграции

Continuous integration server

Local build = server build

  • feature → test-docs.plesk.com
  • stable → docs.plesk.com

Req. 4.2: Контролируемая публикация

Ревью и приёмка через пулл-реквесты

Книга ≈ микросервис

5: Переехать без боли

Проблема 0: инструменты

Исходники через Pandoc

из 21 форматов в 40 форматов

  • HTML
  • MS Word
  • Latex
  • DocBook
  • Markdown
  • reStructuredText

Структуру через Python

~100 строк кода

Проблема 1: источник

Старых версий нет в БД

Прямо из HTML

Проблема 2: всё меняется

Мигрируем кодом

Ручные работы запрещены

Проблема 3: Стили

Источник Результат
20 стилей строки (inline styles) семантические стили в разметке
70 стилей параграфа (paragraph styles) –//–

Решение: карта стилей

Источник Результат
Заголовок № Заголовок №
Внутренняя ссылка docs.plesk.com/... Разметка референсной ссылки
“Special bold” Элемент GUI, термин, ссылка,
Весь код на PHP! PHP, Bash, Python…

Чего бы ещё захотеть?

  • Тестирование документации (уже)
  • Приделать мощную аналитику
  • A/B тесты
  • Интерактивная документация на API

С чего начать

0. Выбор LML

  • Markdown
  • reStructuredText
  • AsciiDoc

Что учесть при выборе

  • Язык разработки: Python, Ruby, JS, Go, Haskell…
  • Форматы публикации
  • Возможности разметки
  • Опыт использования
  • Хотите опенсорсить?

Документируете API?

  • OpenAPI (Swagger)
  • RAML

1. Сделайте прототип

Это будет на мастер-классе в 16:30

Форкните репозиторий на GitHub/GitLab и пробуйте

2. Сотрудничайте и публикуйте через Git

  • Ревью и приёмка через пулл-реквесты
  • Публикация через стабильные ветки
  • Можно в одном репозитории с продуктом

3. Автоматизируйте сразу

  • Локальная сборка = сборка на сервере
  • Человек жмёт кнопку, сервер публикует

4. Мигрируйте

  • Карта преобразования стилей и структуры
  • Pandoc
  • Выбросьте ненужное

5. Drink Your Own Champagne

Документируйте новую систему в самой себе

6. Спрашивайте

  • ru.stackoverflow.com
  • stackoverflow.com

7. Вступайте в сообщества

  • Write The Docs: writethedocs.org
  • Write The Docs Siberia: meetup.com/Write-the-Docs-Siberia
  • Telegram: t.me/technicalwriters
  • Слайды: nick.volynkin.gitlab.io/dlc-ru
  • Почта: nick.volynkin.gmail.com

Мастер-класс

Зарегистрируйтесь на gitlab.com

your.name.gitlab.io

your.name.gitlab.io/X-documentation