Генератор документации программного обеспечения на базе ИИ

Запишите программный рабочий процесс и превратите его в пошаговую документацию со скриншотами. Trupeer фиксирует процесс, генерирует руководство с одним скриншотом на каждый шаг и дает вашей команде черновик для проверки, публикации и обновления, когда интерфейс меняется.

Это нужно для документирования того, как используется ПО, а не для генерации справки по API или спецификаций для разработчиков.

Почему программная документация отличается

Документирование ПО — это не то же самое, что документирование процесса на бумаге, и именно эти различия определяют, что инструмент должен уметь.

• Шаги — это действия в интерфейсе: что нажимать, где и в каком порядке — это утомительно писать и легко ошибиться, полагаясь на память

• Скриншоты должны соответствовать шагу: скриншот неправильного состояния хуже, чем отсутствие скриншота, а отдельное их создание — самая медленная часть при написании документации по ПО

• Интерфейс постоянно меняется: редизайн делает недействительными и формулировки, и каждый скриншот сразу, поэтому программная документация может быстро устаревать, так как интерфейсы меняются часто

Генерация на основе записи напрямую решает первые три задачи: действия наблюдаются, а не восстанавливаются по памяти, скриншоты берутся из самого рабочего процесса, а обновление означает повторную фиксацию, а не переделку с нуля.

Как работает генератор программной документации на основе ИИ

Три шага от ПО в использовании до опубликованной документации.

Шаг 1: Запишите или загрузите рабочий процесс

Зафиксируйте функцию или рабочий процесс в браузере во время использования или загрузите запись, которая у вас уже есть. Документация начинается с записанного рабочего процесса, а не с того, что кто-то потом пытается восстановить его.

Шаг 2: Сгенерируйте руководство по ПО

Trupeer определяет действия в интерфейсе, делает скриншот для каждого шага, готовит текст инструкций и создает озвученное видео на основе той же записи.

Шаг 3: Отредактируйте, опубликуйте и обновите

Просмотрите черновик, поменяйте порядок или перепишите шаги, обрежьте и добавьте пометки к скриншотам, замажьте все чувствительное, затем опубликуйте по ссылке или экспортируйте. Когда интерфейс меняется, повторно запишите затронутую часть.

Проверка не автоматизирована. Все, что не видно на экране, включая то, почему важна настройка, какие есть ограничения и в каких случаях требуется одобрение, все равно нужно добавить. Точность ИИ-документации описывает пробелы, которые стоит проверять.

Зачем использовать генератор программной документации на основе ИИ?

Потому что большая часть усилий в программной документации — это не написание. Это восстановление рабочего процесса по памяти и вручную создание скриншотов, и оба эти действия повторяются каждый раз, когда меняется интерфейс. Именно эту работу и устраняет генератор.

Что вы можете создать с Trupeer

• Руководства по ПО: пошаговые инструкции для функции или рабочего процесса с одним скриншотом на каждый шаг

• Скриншоты: сделанные из рабочего процесса, затем их можно обрезать, добавлять пометки и скрывать чувствительные данные

• Руководства для клиентов: публикуются в базе знаний или распространяются по ссылке

• Видео-обзоры: озвученные, на основе той же записи, как дополнительный результат вместе с письменным руководством

• Внутренняя документация процессов: тот же рабочий процесс, описанный для команды, а не для клиента

• Переведенные версии: публикуются на других языках из одного источника

• Экспорт: PDF или Word, когда нужен файл

Для справки по API, руководств по SDK и спецификаций разработчиков это другая категория. См. инструменты ИИ для технической документации.

Что делает хорошей запись для программной документации

Сгенерированное руководство будет таким же качественным, как и сама фиксация. Есть несколько факторов, которые это определяют, и ни один из них не требует дополнительного времени, если вы их знаете.

• Используйте чистую учетную запись с реалистичными данными:
  пустая тестовая учетная запись дает скриншоты, которые совсем не похожи на то, что видит пользователь, а живая учетная запись помещает данные клиентов в каждое изображение. Подготовленные демоданные — это компромисс, и они экономят время на последующее скрытие

• Начинайте с предсказуемого экрана:
  начните с URL или откройте представление, куда читатель тоже сможет перейти, а не с середины сессии, где уже применены фильтры

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

• Не возвращайтесь назад:
  если вы свернули не туда, перезапустите, а не исправляйте на камеру. Исправленная ошибка часто в итоге документируется как два шага, которые отменяют друг друга

• Держите один рабочий процесс на одну запись:
  две функции в одной фиксации дают одно запутанное руководство, а разделение позже обходится дороже, чем записать дважды

• Установите окно стандартного размера:
  одинаковые размеры в разных записях обеспечивают одинаковые скриншоты по всей библиотеке

Что добавить после фиксации

Запись показывает, что было сделано. Она не показывает, что читателю нужно знать, а для программной документации пробелы достаточно стабильны, чтобы проверять их напрямую.

• Предпосылки: разрешение, роль или тариф, необходимые до первого шага. Обнаружить на шаге семь, что у вас нет доступа, — самая частая причина, почему руководство бросают

• Что настройка делает на самом деле: запись показывает переключатель, который включают/выключают, а не то, как именно меняется результат

• Ограничения и условия: размеры файлов, лимиты по символам, лимиты по скорости и ограничения тарифа, которые проявляются только когда вы их достигаете

• Что произойдет дальше: изменение происходит сразу, ставится в очередь или требует, чтобы кто-то одобрил его

• Альтернативные сценарии: ту же задачу можно выполнить из другого экрана или это массовая версия одного действия

• Что делать, если не получилось: какая ошибка наиболее вероятна у читателя и что она означает

Пример: документирование новой функции

Команда SaaS запускает функцию выставления счетов. Вместо того чтобы писать руководство, делать скриншоты и записывать отдельный обзор, продакт-менеджер один раз записывает рабочий процесс во время тестирования.

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

Где генераторы программной документации на основе ИИ помогают

• Обзоры продуктовых функций: документация по функции, которую нужно выпустить вместе с релизом, а не после него

• Внутреннее обучение по ПО и процессам: админские рабочие процессы, внутренние инструменты и экраны, которые никто не описал

• Онбординг по ПО: новые сотрудники учатся продукту по обзору, а затем работают по письменному руководству

• Руководства для клиентов и поддержки: статьи помощи и руководства по устранению неполадок, которые меняются вместе с продуктом

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

Поддержание программной документации в актуальном состоянии

У программной документации есть проблема сопровождения, которой нет у других типов: изменение интерфейса делает недействительными и скриншоты, и формулировки, а скриншоты — самая дорогая часть, которую приходится переделывать вручную.

Это можно сделать управляемым благодаря двум вещам. Записывайте по разделам, а не одной длинной фиксацией: тогда изменение одного экрана означает повторную запись только этого раздела, а не всего рабочего процесса. И отмечайте, какие руководства охватывают какие функции: когда релиз затрагивает экран, вы знаете, что нужно проверить, а не узнаете об этом из тикета в поддержку.

Чего это не делает

Это не решает, что нужно документировать, не подтверждает, что записанный вами рабочий процесс — это тот, которому должны следовать пользователи, и не предоставляет обоснования, ограничения и одобрения, которых никогда не было на экране. Обновление после изменения обходится дешевле, чем переделка, но все равно кто-то должен заметить, что интерфейс сдвинулся.

Там, где важны ответственность и процессы проверки, шаги редактирования и публикации поддерживают ваш собственный процесс, а не заменяют его.