AI в работе технического писателя
Всем привет! Меня зовут Севара Ахтямова и я работаю техническим писателем — аналитиком около 4 лет. В этой статье я расскажу, как AI помог мне справиться с рабочей рутиной — от генерации toctree до отладки сборки Sphinx-документации. Всё это — на реальных задачах. Я постаралась собрать побольше примеров из личного опыта. Надеюсь, не слишком много.
Во мне с годами побеждает консерватизм и нежелание что-либо менять. Поэтому я несколько лет, что говорят про искусственный интеллект, старательно игнорировала и хейтила его. Несколько раз я пыталась решить какие-то задачи через бесплатный чат gpt, но он каждый раз выдавал мне бред. Я убеждалась, что AI — дурачок и работала дальше.
Хотела бы я сказать, что сама осознала свое невежество, но нет. Меня сильно таки подтолкнул муж, который заикнулся про какие-то там промты. А затем коллега научил их правильно писать.
Как я использую AI
Конечно, с его помощью можно проверить пунктуацию, граматику, инфостиль. Он может написать текст и за вас. Но в этой статье я затрону нетривиальные задачи с техническим уклоном.
Переводчик с матерного на официальный
В случае, когда мне нужно оставить обратную связь, а от гнева забываются приличные слова. Пишу все мысли помощнику и прошу выдать конструктивный текст.
Анализ большого объема информации
Кейс 1: Группировка тикетов по темам
В гите было большое количество тикетов. Хотелось в будущем закрывать их документацией. Я попросила проанализировать все обращения, сделать краткий обзор и разбить по темам.
Пример:
Ознакомься со всеми этими ссылками. Что общего? Я хочу написать статьи, для того, чтобы этих вопросов больше не было. Кратко сформулируй, что написать. |
Кейс 2: Обоснование новой структуры документации
Нужно было придумать новую структуру документации. Старая походила на свалку. Здесь подход, как в прошлом кейсе. Выгрузила данные в AI и попросила помощи в структурировании с обоснованием.
Мартышкин труд
Кейс 3: Списки с экранов — в текст
Иногда в работе нужно переносить интерфейс программы в текст.
Я загрузила серию скриншотов, содержащих списки настроек и параметров. AI распознал текст с изображений, убрал артефакты, визуальные метки и расставил элементы в виде чистого, структурированного списка. Это помогло быстро перенести данные в документацию без ручной расшифровки.
Пример:
На скриншотах список. Распознай текст и выдай в виде маркированного списка, сортируя слова по алфавиту. |
Кейс 4: Автоматическая генерация toctree из списка объектов
Моя работа предполагает написание текста в .rst разметке. Чтобы задать toctree, нужно написать:
… toctree: : name: Исходящие документы : maxdepth: 1 ПолучитьТаблицуИспользуемыхПакетов |
У меня был большой список на русском языке этих объектов. Нужно было занести его в toctree. Вместо того, чтобы делать это вручную, я составила промт, где попросила записать имена в нужном оформлении с транслитерацией и составить по алфавиту.
Пример:
У меня есть список элементов в файле Исходный текст. Необходимо преобразовать этот список в разметку reStructuredText. Каждый элемент на русском языке — это заголовок. Заголовок подчеркивается »--------». Следующая строка после подчеркивания — пустая. После этого вставляем блок:
В поле »: name:» вставляем имя соответствующего заголовка. Следующая строка после »: maxdepth: 1» — пустая. Затем вставляем элементы на английсском языке. К каждому элементу на английсском языке дописываем <>. Внутри <> дублируем название элемента. Важное условие: у всех строк, кроме заголовка, подчеркивания заголовка и »… toctree::» должно быть ровно 3 пробела перед текстом. Важное условие: не удаляй ничего из исходного текста. За каждое несоответствие с правилами, которые я написала, я буду убивать одного котика. Пожалуйста, выведи итоговый файл с текстом, где каждый элемент списка оформлен в соответствии с описанными требованиями. Для наглядности посмотри пример, который я приложила. |
Кейс 5: Построение дерева файловой структуры по архиву
Мне нужно было схематично изобразить внутреннее дерево документации. Для этого я закинула папку с файлами и попросила создать дерево.
Пример:
Когда-то существовал проект, чья внутренняя структура соответствовала структуре из файла «Схема». Сейчас этот проект изменился. Я отправила измененный вариант архивом «docs». Посмотри, какую структуру имеет нынешний архив «docs». Распиши структуру «docs» по примеру файла «Схема». Важное условие: Записывай все файлы из архива «docs». |
Здесь мне пришлось подправить результат ручками и получилось:
Сборка, оформление и отладка Sphinx-документации
Кейс 6: Диагностика и фиксы ошибок при сборке
После обновления окружения при сборке sphinx возникали ошибки: Could not open requirements file, ModuleNotFoundError: No module named 'six', image file not readable. Здесь у меня не было единого промта, но его можно было бы составить примерно так:
Пример:
Помоги отладить сборку Sphinx — не работают пути к изображениям, конфликтуют зависимости и после удаления alabaster всё ломается. Помоги проверить актуальные версии установленных библиотек для Sphinx, избавиться от лишнего (например, alabaster), понять, зачем каждая нужна, и правильно зафиксировать зависимости без конфликтов. |
В ответ я получила подробную диагностику, объяснение, как обрабатываются пути и стили, рекомендации по настройке layout.html и sphinx_design, а также безопасное решение конфликта зависимостей. Это помогло собрать документацию и улучшить интерфейс.
Кейс 7: Сворачиваемые блоки
Я хотела улучшить сканируемость текста и завернуть информацию об устаревших полях в раскрывающиеся блоки.
Пример:
Хочу добавить сворачиваемые блоки в документацию на Sphinx с темой Read the Docs. Подскажи, как это сделать так, чтобы они работали и были изначально закрыты. |
AI предложил использовать:
… dropdown: ⚠️ Устаревшие поля |
Также он:
Помог установить и подключить sphinx_design.
Объяснил, что нужно использовать кастомный layout.html с блоком