Everything-as-code и документация в том числе!

Большое количество современных веб-проектов переходит на микросервисную архитектуру. Она решает огромное количество
проблем, присущих монолитным системам. Но микросервисы тоже нужно документировать :)

Популярный подход docs-as-code (документация как код) хорошо применим к микросервисам.
На порталах вроде github.com его легко начать использовать – кладете файл README в корень проекта и все.

Однако, в корпоративной разработке есть ряд ограничений, мешающий внедрению этого подхода:

* непрерывный рефакторинг большого монолита на микросервисы (как ремонт в квартире - начали и пока не закончили)
* территориально-распределенные команды из разных стран
* привычка разработчиков откладывать написание документации "на потом".
* зафиксированный стек используемых технологий и инструментов (в нашем случае это Java, Maven, Confluence)

В докладе рассмотрены темы:

1. Виды документации. Разработческая, пользовательская, документаци на API
2. Подход docs-as-code. Какие проблемы решает.
3. Обзор средств автоматизации работы с документацией
4. Сравнение форматов документации: Markdown, AsciiDoc, reStructuredText
5. PlantUML - генерация диаграмм и схем из текстового описания
6. Confluence - плюсы, минусы, особенности работы
7. Журнал архитектурных решений как код.

Рассказ о том, как подход docs-as-code развивается в компании Ingram Micro.