Комментарии 4
К сожалению все эти вещи не решают главную проблему: создание хорошей документации :(
Ну поменяли мы формат хранения данных, вытащили в отдельное место и что? это ничего не меняет. Это не документация. Сейчас среды разработки позволяют навигацию по этой же информации гораздо более удобную чем HTML|PDF или что-то подобное.
Замечательный пример — документация QT. Мне пришлось недавно столкнутся с ним. Я уже устал шариться по безумным размерам страницам в поисках нужной информации, но получаю дупликат того что я вижу в студии. И эта информация не отвечает на вопросы как. Она не сгруппирована по важности. Не объсняет принципов и тп. Искать по этой информации просто ужас. А главное она не нужна, она и так уже есть в другом виде, но есть.
Главную задачу в данном случае решает ответственный подход каждого разработчика к описанию созданного им функционала.
Навигация и поиск упрощаются за счёт введённой системы тегов, которые ведутся в алфавитном порядке и содержат направление разработки, к которому относятся, и краткое описание того, что делают объединённые ими ручки.
Приводимый вами пример — документация для внешних пользователей, в статье же речь идёт об инструменте обмена информацией внутри команды, который, как показывает практика, успешно работает и облегчает коммуникацию.
Спасибо за указание на интересный продукт, у Qt на беглый взгляд и правда подробная и хорошо структурированная документация!
Docs as Code. Часть 2: получаем документацию из кода