Николай Волынкин
Упоминаемые языки, инструменты, другие ресурсы будут сопровождаться ссылками.
Презентация всегда будет доступна по адресу
Вопросы — в конце лекции.
Если вы не успеете задать вопрос или придумаете его после лекции:
Тема огромная, постараемся успеть понемногу.
но не успеем точно.
Здесь «мы» — это все, причастные к разработке документации:
Docs like/as code (документация в форме кода) — это подход к разработке документации, в котором мы:
Как DevOps, только про документацию.
Текст, изображения, видео, скачиваемые файлы.
Структура: абзацы, заголовки, документы, книги.
Легковесные языки разметки (lightweight markup languages).
Пишем структурированный текст, который:
Для работы достаточно текстового редактора.
В хороших редакторах есть подсветка синтаксиса и предпросмотр результата.
Общие: |
|
Специальные: |
|
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).
Это инструменты, которые преобразуют исходный код в форматы для публикации.
В процессе сборки создаётся представление документа — то, как читатель видит и может использовать документацию.
Содержимое и представление отделены друг от друга. Для одного содержимого может быть несколько представлений (например, сайт, PDF, печать).
Да, это тот самый принцип единого источника (single source). Он же в программировании – Single Point of Truth (SPOT) и Don’t Repeat Yourself (DRY).
Тема (theme) — набор стилей и шаблонов, определяющих представление конечного формата.
Как правило, тема предназначена для конкретного фреймворка.
Готовых тем множество, можно редактировать или создавать темы для своих задач. (Понадобится фронтенд-разработчик).
Вообще всю настройку сборки можно делегировать разработчику.
(некоторые наиболее популярные)
Фреймворк: | MD | rST | AsciiDoc |
---|---|---|---|
Jekyll | + |
- |
- |
Sphinx | - |
+ |
- |
AsciiDoctor | - |
- |
+ |
Hugo | + |
+/- |
+/- |
Hexo | + |
- |
- |
Nikola | + |
+ |
- |
Pandoc – швейцарский нож техписателя.
Конвертирует из ~20 форматов в ~40 форматов.
Все использованные инструменты бесплатны. Знать HTML, CSS и Javascript не нужно.
Давайте «поиграем шрифтами».
Происходит переключение между таблицами стилей (.css
) с разными темами оформления.
Ура, мы можем хранить наш код в системе контроля версий!
Можем сравнить две любые версии вплоть до пробела или запятой.
git diff
Достоверно знаем, кто, когда и зачем редактировал каждую строку.
git blame
Все составляющие доступны машине:
Можно собирать и публиковать документацию. Кто будет это делать?
Можно руками, но лучше…
Continuous integration (CI) server.
Кратко: машина, способная самостоятельно и по запросу выполнять заранее запрограммированные задачи.
Дальше — DevOps. Делегируйте эту задачу системным администраторам.
Вся задействованная инфраструктура тоже бесплатна. Навыки системного администратора не требуются.
Сборка сайта на рабочей машине (2 секунды):
make html
Можно автоматизировать сборку по каждому изменению исходного кода, но пока руки не дошли.
Подготовка окружения, сборка и публикация на сервере 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
Используем функциональность пулл-реквестов (pull-request).
Это запрос на вливание ваших изменений в основную ветку разработки.
Все общие требования, которые мы предъявляем к документации:
Представление задано в одном месте (single point of truth) и применяется автоматически ко всему документу.
Когда меняются требования к оформлению, мы редактируем тему.
С ГОСТами сложнее. Но если один раз реализовать нужную тему, она будет работать.
Богатые возможности.
Ограничение: такие инструменты потребуют точной настройки под ваш проект, но всё равно будут иногда создавать ложноотрицательные результаты тестов.
Поскольку мы используем один инструментарий с разработчиками, мы можем синхронизировать версии документации и версии продукта.
Возможный путь — хранить код документации в одном репозитории с кодом продукта.
Покрытие (термин из области тестирования) — доля программного кода или «маршрутов» алгоритма, для которой есть тесты.
Есть инструменты, позволяющие оценить покрытие кода документацией.
С остальной документацией всё как раньше: её должны проверять эксперты предметной области и наши коллеги-писатели.
Презентация:
nick.volynkin.gitlab.io/itgm10
Код этой презентации: