От набора PDF-файлов до портала технической документации на 2,5 тысячи статей

Вот важная новость с фронта ИИ: xtraroman 38 минут назад От набора PDF-файлов до портала технической документации на 2,5 тысячи статей Средний 13 мин 1. 2K Блог компании ЭРЕМЕКС . NET * Подготовка технической документации * Кейс У инженеров, которые проектируют электронные устройства, документация в виде PDF пользуется большой популярностью.

Вспомним, к примеру, даташиты к электронным компонентам. Поэтому и наши САПР поставляются с комплектом PDF-файлов, которые рассказывают про особенности установки и эксплуатации. Долгое время документация выпускалась только так: вместе с каждым релизом продукта в виде набора PDF.

Технические детали

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

Как было: документация как часть релиза, а не как сервисHelp&Manual представляет собой нишевый, но довольно популярный среди технических писателей инструмент для авторинга: WYSIWYG-редактор, единый проект, экспорт в разные форматы. Мы использовали его много лет и на выходе получали документацию в виде набора PDF-файлов, по одному или нескольким файлам на продукт. Формат, который десять лет назад выглядел разумным выбором, со временем начал создавать всё больше проблем:Поиск внутри PDF неудобен.

Стандартный поиск по Ctrl+F работает только внутри одного файла и плохо справляется даже с этим, особенно когда документ разрастается до сотен страниц. PDF оставался невидимым для поисковых систем и нейросетей. Пользователь, искавший решение проблемы с нашим продуктом, не находил наших же документов: поисковая выдача показывала форумы и сторонние обсуждения.

Отраслевые последствия

По той же причине ни один AI-ассистент не располагал сведениями о наших продуктах, поскольку содержимое статичных PDF-файлов поисковые системы индексируют неохотно. Документация обновлялась только вместе с релизом продукта. Процесс был жёстко связан: до релиза изменения в документацию не вносились, после релиза она оставалась неизменной до следующего выпуска.

Если ошибку в статье обнаруживали через неделю после выхода версии, исправление откладывалось на месяцы. Стало очевидно, что проблема не в Help&Manual как редакторе: писатели к нему привыкли, и переучивать их не было необходимости. Проблема состояла в том, каким образом контент превращался в готовую документацию и доходил до пользователя.

Шаг первый: автоматический выход из Help&ManualГлавным условием было сохранить процесс работы технических писателей в неизменном виде. Help&Manual хранит каждую статью в виде XML-файла, а значит, контент можно трансформировать программно, без участия человека.

Событие, по словам экспертов, усилит конкуренцию в сфере ИИ.