(6) Техническая документация в IT-проектах. Docs-as-code на примере инструмента Foliant

Slide 1

Slide 1 text

Документация как код на примере Foliant Константин Валеев, май 2020

Slide 2

Slide 2 text

Привет! • Руковожу отделом аналитиков и техписателей в «Ростелеком ИТ» — софтверной дочке «Ростелекома». • Разрабатываем свой инструмент ведения документации — Foliant.

Slide 3

Slide 3 text

О чём поговорим 1. Кратко обсудим Docs as Code: что это, когда полезен, какие есть ограничения. 2. Посмотрим как этот подход можно реализовать. 3. Немного взглянем на то, что умеет Foliant.

Slide 4

Slide 4 text

Docs-as-Code

Slide 5

Slide 5 text

Docs-as-Code 1. Ведение документации в текстом формате — человекочитаемой разметке. 2. Использование инструментов и подходов разработки кода. 3. Плюсы: не нужна отдельная инфраструктура; легко поднимается; понятно и нативно для команды разработки; все плюшки инструментов для работы с кодом. 4. Минусы: сложнее в использовании, не разработчикам придётся привыкнуть, необходимо соблюдать правила работы с инструментами, нужно развернуть и поддерживать.

Slide 6

Slide 6 text

Процесс работы над документацией Над документацией работают так же, как над кодом: 1. Исходные тексты документации в человекочитаемой разметке. 2. Хранятся в системе контроля версий (git). 3. Релиз через Continues Integration: на веб-сайт, в PDF и Word.

Slide 7

Slide 7 text

Используем инфраструктуру разработки 1. Текст кода ➝ Текст документа 2. VCS для кода ➝ VCS для документации 3. MR для код-ревью ➝ MR для ревью документации 4. CI для сборки кода ➝ CI для сборки документации 5. Code Style и релизные политики ➝ Styleguide и соглашения 6. Автотесты сборки ➝ Автотесты документации

Slide 8

Slide 8 text

Source Code ➝ Source Docs • Markdown • RestructuredText • Asciidoc

Slide 9

Slide 9 text

Системы контроля версий

Slide 10

Slide 10 text

Ветки

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

https:/ /www.youtube.com/ watch?v=5N3zyvXB6Jg

Slide 13

Slide 13 text

Code Review ➝ Doc Review Мердж-реквесты для согласования документации: читают не только разаработчики (маркдаун легко читается и в исходнике), связь с тикетами в джире.

Slide 14

Slide 14 text

DevOps ➝ DocOps © Thomas Pryce

Slide 15

Slide 15 text

Автотесты • Линтинг разметки и орфографии при сборке • Валидность ссылок • Соответствие глоссарию • Стоп-слова • Что угодно

Slide 16

Slide 16 text

Переиспользования при сборке • Вставка других текстов • Вставка сниппетов кода • Генерация диаграмм • И даже исполнение кода

Slide 17

Slide 17 text

Сборка: PDF и Word (Pandoc)

Slide 18

Slide 18 text

Сборка: Сайт (MkDocs)

Slide 19

Slide 19 text

Сборка: Сайт (Slate)

Slide 20

Slide 20 text

Сборка: Google Docs (Pandoc/pyDrive)

Slide 21

Slide 21 text

Сборка: Conﬂuence

Slide 22

Slide 22 text

Foliant

Slide 23

Slide 23 text

Foliant • Markdown-based • Клей между хорошими инструментами • Модульность и расширяемость • Unix-way

Slide 24

Slide 24 text

Как пользуемся • Пишем в маркдауне • Несколько проектов • Центральный проект для сборки • Мердж-реквесты и вычитка • Gitﬂow и Trunk-based • CI/CD

Slide 25

Slide 25 text

Спасибо! hello@kvaleev.me @kvaleev