Привет, Хабр! Меня зовут Виктория Юльская, и я старший системный аналитик в Ozon.

Я думаю, здесь найдётся много людей, которые хоть раз работали с документацией API в Confluence. Да-да, те самые километровые страницы на каждый метод — с описанием всего и вся в виде текста, таблиц, диаграмм последовательности и т. д.

Зачастую такая документация API в Confluence устаревает ровно в тот момент, как её закончили писать. После передачи задачи в разработку, как только что-то непонятно, куда все идут? Правильно, к аналитику — «А как это работает? А что это значит? А что если...?».

Ну вот же дока, там все написано... но обычно никто не хочет читать огромную доку на метод, быстрее же спросить. И зачастую у самих аналитиков есть вопросики по актуальности этой документации (уже есть новые договорённости со встреч, комментарии в документации и т. д.).

Есть ли более эффективный способ ведения и поддержания документации API в актуальном состоянии? Давайте разбираться.