Всем привет! Меня зовут Севара Ахтямова и я работаю техническим писателем — аналитиком около 4 лет. В этой статье я расскажу, как AI помог мне справиться с рабочей рутиной — от генерации toctree до отладки сборки Sphinx-документации. Всё это — на реальных задачах. Я постаралась собрать побольше примеров из личного опыта. Надеюсь, не слишком много.
Во мне с годами побеждает консерватизм и нежелание что-либо менять. Поэтому я несколько лет, что говорят про искусственный интеллект, старательно игнорировала и хейтила его. Несколько раз я пыталась решить какие-то задачи через бесплатный чат gpt, но он каждый раз выдавал мне бред. Я убеждалась, что AI — дурачок и работала дальше.
Хотела бы я сказать, что сама осознала свое невежество, но нет. Меня сильно таки подтолкнул муж, который заикнулся про какие-то там промты. А затем коллега научил их правильно писать.
Как я использую AI
Конечно, с его помощью можно проверить пунктуацию, граматику, инфостиль. Он может написать текст и за вас. Но в этой статье я затрону нетривиальные задачи с техническим уклоном.
Переводчик с матерного на официальный
В случае, когда мне нужно оставить обратную связь, а от гнева забываются приличные слова. Пишу все мысли помощнику и прошу выдать конструктивный текст.
Анализ большого объема информации
Кейс 1: Группировка тикетов по темам
В гите было большое количество тикетов. Хотелось в будущем закрывать их документацией. Я попросила проанализировать все обращения, сделать краткий обзор и разбить по темам.
Пример:
|
Ознакомься со всеми этими ссылками. Что общего? Я хочу написать статьи, для того, чтобы этих вопросов больше не было. Кратко сформулируй, что написать. |
Кейс 2: Обоснование новой структуры документации
Нужно было придумать новую структуру документации. Старая походила на свалку. Здесь подход, как в прошлом кейсе. Выгрузила данные в AI и попросила помощи в структурировании с обоснованием.
Мартышкин труд
Кейс 3: Списки с экранов — в текст
Иногда в работе нужно переносить интерфейс программы в текст.
Я загрузила серию скриншотов, содержащих списки настроек и параметров. AI распознал текст с изображений, убрал артефакты, визуальные метки и расставил элементы в виде чистого, структурированного списка. Это помогло быстро перенести данные в документацию без ручной расшифровки.
Пример:
|
На скриншотах список. Распознай текст и выдай в виде маркированного списка, сортируя слова по алфавиту. |
Кейс 4: Автоматическая генерация toctree из списка объектов
Моя работа предполагает написание текста в .rst разметке. Чтобы задать toctree, нужно написать:
|
.. toctree:: :name: Исходящие документы :maxdepth: 1 ПолучитьТаблицуИспользуемыхПакетов <Poluchit’TablitsuIspol’zuyemykhPaketov> |
У меня был большой список на русском языке этих объектов. Нужно было занести его в 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 с блоком <style>, чтобы таблица в dropdown корректно отображалась.
-
Рассказал, почему блок по умолчанию развернут и как это менялось с версией.
В заключение
Теперь я меньше устаю от рутины, реже отвлекаю коллег и почти не сижу на Stack Overflow. AI стал частью моего рабочего процесса. Я каждый раз радуюсь, какие оригинальные решения мы с ним придумываем.
Надеюсь, мои кейсы помогут кому-то сэкономить пару часов, нервов и кофе. Если у вас похожие задачи — просто попробуйте. А если что, AI подскажет.
Автор: nyygnet
