За три года генеративный ИИ превратил черновик текста из дорогого результата в дешёвую операцию. Главный вопрос теперь не в том, умеет ли модель писать, а в том, кто отвечает за факты, структуру, проверку, обновление и качество документации после того, как текст стало возможно получать за минуты.
Docs-as-Code — это не требование посадить всех техписов в IDE. Разбираем нормальный путь: где хранить исходники, как редактировать их прямо в браузере, какие проверки отдавать автоматике, как устроить ревью и как измерить реальную экономию времени.
Хорошая API-документация сочетает машиночитаемый контракт, человеческие объяснения, запускаемые примеры и явное описание ошибок. У REST API-документации сразу две аудитории: машины и люди.
Инструменты изменились радикально, но ядро профессии удивительно узнаваемо: аудитория, факты, структура, терминология и ответственность. В 2006 году технический писатель заметно чаще жил в настольных издательских системах, офисных форматах и вручную поддерживаемых help-системах.
Sphinx, MkDocs, Astro и другие генераторы оптимизированы под разные модели контента и команды. Сравнивайте авторский процесс, расширяемость, локализацию и стоимость сопровождения, а не красоту демо и длину списка функций. Демо генератора может выглядеть великолепно и при этом не подходить вашей документации.
Поиск по документации нужно выбирать и настраивать вокруг запросов, которые пользователь не может разрешить, а не вокруг длинного списка функций поставщика. Поиск особенно полезен, когда читатель знает термин или симптом, но не знает, где лежит информация.
Диаграммы, заданные текстом, удобно сопровождать и проверять, но только если визуальная задача соответствует тому, что выбранная нотация умеет выражать понятно. Диаграммы как код хорошо подходят для потоков, состояний, зависимостей и последовательностей, где главное — связи.
Относитесь к документации как к сборочному артефакту: проверяйте структуру, ссылки, примеры и правила публикации до того, как изменения увидят читатели. CI не решит, полезно ли объяснение читателю, но способен отсеять множество предсказуемых дефектов до того, как на них потратит время человек.
От инженерных записок Возняка и ручного paste-up 1982 года до Inside Macintosh, HIG, DocC, Markdown и агентов Xcode.
Bengaluru, India
Мероприятия →Berlin, Germany
Мероприятия →Toronto, Canada
Мероприятия →Идеи, методы и споры предыдущих поколений технических писателей — с новым контекстом и современными выводами.