Сказ о том как документацию лечили да автоматизировали

Доклад (40 минут)

Павел Абдюшев

Конференция: ЛАФ-2021
Жил был продукт для больших компаний. С хорошей документацией, которую команда вела в конфлюенс.
Продукт рос, документация пухла, но оставалась хорошей.
Число заказчиков тоже увеличивалось, а под каждого заказчика появлялось новое пространство с описанием продукта — с одной стороны, унаследованном от общей документации, а с другой — описывающее специфичные для заказчика доработки и настройки.
В какой-то момент выросшая документация выросла настолько, что вышла из-под родительского контроля команды:

• Перестала быть понятной для заказчиков — где их настройки, а где общие, что и как нужно использовать для интеграции с системой.
• Постоянно требовала внимания и актуализации.
• Каждое пространство стремилось стать уникальным по своей структуре и выделиться на фоне остальных.
• При изменениях в ядре продукта все простанства требовали актуализации одновременно.

Но команда не растерялась и отправила документацию на лечение.
О проведенном процессе исцелении я и расскажу в докладе:

1. Как мы переработали структуру нашей документации.
2. Как автоматизировали создание и обновления описания самых больных разделов:

•  модели данных;
•  задач по обработке данных внутри приложения, их параметров;
•  пакетов задач и их расписания;
•  примеров запросов к API;
•  release notes для заказчика.

1. Каких успехов уже достигли:

•     уменьшили число обращений от заказчиков из-за неактуальной документации;
•     упростили поддержку и поиск;
•     стали больше доверять нашей документации;
•     ускорили передачу поддержки заказчиков между коллегами.

1. С какими техническими и организационными проблемами столкнулись в процессе оздоровления и что планируем сделать в ближайшем будущем.