Welcome to Docs like code’s documentation!

Docs like code

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

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

  • Технический писатель, Plesk.
  • Модератор сообщества Stack Overflow на русском
  • Ранее: автоматизация тестирования, 2GIS
  • Ещё ранее: разработка мобильных приложений

Ссылки

Упоминаемые языки, инструменты, другие ресурсы будут сопровождаться ссылками.

Презентация всегда будет доступна по адресу

nick.volynkin.gitlab.io/itgm10

Термины

Все вводимые термины будут продублированы на английском языке, потому что литературы на русском почти нет.

Вопросы

Вопросы — в конце лекции.

Если вы не успеете задать вопрос или придумаете его после лекции:

nick.volynkin@gmail.com

Что мы обсудим

Тема огромная, постараемся успеть понемногу.

  1. Что такое «документация как код».
  2. Что может быть кодом (почти всё).
  3. Возможности и ограничения подхода.
  4. Обзор инструментов.
  5. С чего начать.

Что хотелось бы обсудить

но не успеем точно.

  • Совместная работа над документацией,
  • Локализация,
  • Полнотекстовый поиск,
  • Agile,
  • Тестирование документации,
  • Crowdsourcing.

Аудитория

Здесь «мы» — это все, причастные к разработке документации:

  • Технические писатели,
  • Аналитики,
  • Тестировщики,
  • Разработчики ПО,
  • Руководители,
  • Неравнодушные читатели,
  • Любой, у кого душа болит о документации.

Смысл и суть

Docs like/as code (документация в форме кода) — это подход к разработке документации, в котором мы:

  • Разрабатываем документацию как программный код: пишем в текстовом редакторе, а потом «компилируем» в конечный продукт.
  • Используем лучшие практики и инструменты, придуманные для разработки ПО.
  • Отдаём машине все рутинные задачи и занимаемся любимым делом.

Как DevOps, только про документацию.

Этим кто-то пользуется?

  • Linux Kernel
  • Microsoft
  • Openstack
  • Ansible
  • GitLab

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

  1. Содержимое (content)
  2. Представление (representation)
  3. Сборка (building)
  4. Хранение и версионирование (storage, version control)
  5. Публикация (publishing)
  6. Рабочий процесс (workflow)
  7. Руководства и требования (guides and requirements)

Содержимое

Текст, изображения, видео, скачиваемые файлы.

Структура: абзацы, заголовки, документы, книги.

Код

Легковесные языки разметки (lightweight markup languages).

Пишем структурированный текст, который:

  • Легко читается человеком без специального ПО.
  • Имеет структурную и семантическую разметку и может однозначно обрабатываться машиной.

Редактор

Для работы достаточно текстового редактора.

В хороших редакторах есть подсветка синтаксиса и предпросмотр результата.

Популярные языки:

Общие:
  • Markdown
  • reStructured Text
  • AsciiDoc
Специальные:
  • Для документирования API (OpenAPI)
  • Коментарии к коду (Doxygen)
  • Особого назначения (LaTeX)

Заголовок

Markdown:

# Header 1

Text...

reStructured Text:

Header 1
========

Text...

Ссылка

Markdown:

Hello, [ITGM 10](http://piter-united.ru/itgm10/)!

reStructured Text:

Hello, `ITGM 10`_!

.. _`ITGM 10`: http://piter-united.ru/itgm10/

Результат:

Hello, ITGM 10!

Фрагмент кода

Markdown:

```bash
echo 'hello world'
```

reStructured Text:

..  code-block:: bash

    echo 'Hello, ITGM10!'

Результат:

echo 'Hello, ITGM10!'

Оглавление

Markdown

Просто делаем список со ссылками:

# Contents

* [Chapter 1](/chapter-1)
    * [Paragraph 1](/chapter-1/#paragraph-1)
* [Chapter 2](/chapter-2)
* [Chapter 3](/chapter-3)

reStructured Text

Описываем структуру документа:

..  toctree::
    :maxdepth: 2
    :caption: Contents

    chapter1
    chapter2
    chapter3

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

Получаем комплект документации, который можно отдавать:

  • На рецензирование (проверку, ревью)
  • На приёмку
  • Читателю (заказчику)

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

Используем фреймворки документации (documentation frameworks).

Это инструменты, которые преобразуют исходный код в форматы для публикации.

Представление

В процессе сборки создаётся представление документа — то, как читатель видит и может использовать документацию.

  • Шрифты и стили оформления текста
  • Видимая структура и навигация по документам
  • Пользовательский опыт (user experience)

Представление

Содержимое и представление отделены друг от друга. Для одного содержимого может быть несколько представлений (например, сайт, PDF, печать).

Да, это тот самый принцип единого источника (single source). Он же в программировании – Single Point of Truth (SPOT) и Don’t Repeat Yourself (DRY).

Темы

Тема (theme) — набор стилей и шаблонов, определяющих представление конечного формата.

Как правило, тема предназначена для конкретного фреймворка.

Готовых тем множество, можно редактировать или создавать темы для своих задач. (Понадобится фронтенд-разработчик).

Вообще всю настройку сборки можно делегировать разработчику.

Фреймворки

(некоторые наиболее популярные)

Фреймворк: MD rST AsciiDoc
Jekyll + - -
Sphinx - + -
AsciiDoctor - - +
Hugo + +/- +/-
Hexo + - -
Nikola + + -

Pandoc

Pandoc – швейцарский нож техписателя.

Конвертирует из ~20 форматов в ~40 форматов.

Drink Your Own Champagne

Эта презентация — тоже объект документации.

Разработка

  • Исходный код в разметке reStructured Text (rST).
  • Из исходного кода в rST помощью инструмента Sphinx и темы sphinxjp.themes.revealjs собирается код сайта (HTML, CSS и Javascript).
  • Этот код основан на специальном фреймворке для презентаций — reveal.js.

Все использованные инструменты бесплатны. Знать HTML, CSS и Javascript не нужно.

Разработка: процесс

_images/workflow.png

Разработка: процесс

_images/workflow2.png

Представление

Давайте «поиграем шрифтами».

Происходит переключение между таблицами стилей (.css) с разными темами оформления.

Хранение и контроль версий

Ура, мы можем хранить наш код в системе контроля версий!

  • Git
  • И другие

Контроль версий

  • Можем связать версию продукта и версию документации.
  • Можем сохранять черновики или копить обновления к релизу.
  • Не боимся всё потерять, если сервер сгорит.

Diffability

Можем сравнить две любые версии вплоть до пробела или запятой.

git diff
_images/diffability.png

Blameability

Достоверно знаем, кто, когда и зачем редактировал каждую строку.

git blame
_images/blame.png

Публикация

Как мы передаём документацию читателю.

Настало время автоматизации

Все составляющие доступны машине:

  • Исходный код лежит в системе контроля версий
  • Фреймворки и темы оформления описываются как зависимости в файлах конфигурации
  • Что и как собирать — инструкция в соседнем файле.

Можно собирать и публиковать документацию. Кто будет это делать?

Можно руками, но лучше…

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

Continuous integration (CI) server.

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

Дальше — DevOps. Делегируйте эту задачу системным администраторам.

Drink Your Own Champagne

Хранение, сборка и публикация

  • Код хранится в локальном git-репозитории, оттуда отправляется на GitLab.com
  • Сборка и публикация происходит на сервере непрерывной интеграции GitLab CI. Используются серверные мощности из облака, предоставленного DigitalOcean.
  • Сайт хостится с помощью сервиса GitLab Pages на nick.volynkin.gitlab.io/itgm10.

Вся задействованная инфраструктура тоже бесплатна. Навыки системного администратора не требуются.

Локальная сборка

Сборка сайта на рабочей машине (2 секунды):

make html

Можно автоматизировать сборку по каждому изменению исходного кода, но пока руки не дошли.

_images/build.png

Сборка и публикация

Подготовка окружения, сборка и публикация на сервере CI (~2 минуты):

image: alpine

pages:
  script:
  - apk --no-cache add py2-pip python-dev
  - pip install -r requirements.txt
  - apk --no-cache add make
  - make html
  - mv build/html/ public/
  artifacts:
    paths:
    - public
  only:
  - master

Сборочные конвейеры на GitLab CI

_images/pipelines.png

Рабочий процесс

  • Как мы ставим задачи на разработку документации?
  • Как мы фиксируем ошибки?
  • Как происходит рецензирование документа?
  • Как происходит приёмка документа?

Задачи на разработку и ошибки

Тот же трекер задач, почти ничего нового.

Рецензирование и приёмка

Используем функциональность пулл-реквестов (pull-request).

Это запрос на вливание ваших изменений в основную ветку разработки.

  • Видны изменения исходного кода, можно обсуждать каждую строку.
  • Можно обсуждать запрос в целом.
  • Право принять изменения обычно есть у того, кто принимает решение о приёмке.
  • Если настроить — виден готовый к публикации результат. Например, документация публикуется на тестовом сайте.

Пример

_images/pull-request.png

Стандарты и требования

Все общие требования, которые мы предъявляем к документации:

  • Оформление (заголовки, ссылки, библиография, отступы)
  • Язык (грамотность, словарь, синтаксис)
  • Актуальность и версионируемость
  • Корректность и полнота

Оформление

Представление задано в одном месте (single point of truth) и применяется автоматически ко всему документу.

Когда меняются требования к оформлению, мы редактируем тему.

С ГОСТами сложнее. Но если один раз реализовать нужную тему, она будет работать.

Язык

Богатые возможности.

  • Есть инструменты для проверки орфографии и пунктуации.
  • Можно реализовать проверку словаря.
  • Если вы умеете Natural Language Processing, возможностей становится больше.

Ограничение: такие инструменты потребуют точной настройки под ваш проект, но всё равно будут иногда создавать ложноотрицательные результаты тестов.

Актуальность и версионируемость

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

Возможный путь — хранить код документации в одном репозитории с кодом продукта.

Корректность и полнота

Покрытие (термин из области тестирования) — доля программного кода или «маршрутов» алгоритма, для которой есть тесты.

Есть инструменты, позволяющие оценить покрытие кода документацией.

С остальной документацией всё как раньше: её должны проверять эксперты предметной области и наши коллеги-писатели.

С чего начать в понедельник

  • Напишите «Привет, мир!» в онлайн-редакторе: http://dillinger.io/
  • Посмотрите на различные готовые решения: насколько вам нравится эта документация, удобно ли её читать.
  • Что используют ваши разработчики?
    • Система контроля версий
    • Сервер CI
    • Внутренняя документация (архитектурная, в коде, тестовая)

Вопросы

nick.volynkin@gmail.com

Презентация:

nick.volynkin.gitlab.io/itgm10

Код этой презентации:

gitlab.com/nick.volynkin/itgm10/tree/master