Недавно я решил перечитать рассказ «В исправительной колонии» Франца Кафки. Впервые я познакомился с ним еще студентом — задолго до того, как узнал о существовании профессии технического писателя.
Теперь я смотрел на него совсем иначе — глазами, которые видели тысячи страниц руководств, справочников и API‑документации.
И в какой‑то момент мне в голову пришла довольно абсурдная мысль: я читаю не просто рассказ Кафки — я читаю почти готовую техническую документацию.
В центре повествования — сложный механический аппарат, который главный герой рассказа, офицер, описывает с инженерной точностью. Я ловил себя на том, что в процессе чтения то и дело натыкаюсь на типы информации, так знакомые техническому писателю. Вот офицер подробно описывает устройство аппарата. Чуть дальше объясняет принцип его работы. Затем переходит к пошаговым действиям оператора. Через несколько страниц я нахожу самый что ни на есть траблшутинг. А во второй половине рассказа и вовсе обнаруживаю чейнджлог — небольшой, но вполне узнаваемый.
Тогда возникла идея: а что если превратить этот текст в полноценное руководство по эксплуатации? Привести его к современным стандартам: структурировать, упростить формулировки, убрать лишнее, добавить наглядность и оформить в таком виде, в каком мы сейчас привыкли видеть техническую документацию. И, разумеется, подключить к этому процессу большие языковые модели.
Изначально это был просто эксперимент. Но в процессе его реализации появились наблюдения, которыми имеет смысл поделиться.
Впрочем, давайте по порядку.
Что написано пером, то вырубишь топором
Для начала нужно было подготовить сырой исходник, на основе которого ИИ должен был написать черновой технический документ.
Можно было просто скормить LLM рассказ целиком? Думаю, да. Ведь 66 КБ для современных моделей — это даже не разминка. Но я решил перестраховаться: вдруг машина что‑то пропустит или интерпретирует слишком творчески. Поэтому я вручную прошелся по тексту и собрал нужные фрагменты в одном месте. На всё про всё ушло не больше часа.
На этом этапе хирургическая точность не требовалась. Я действовал максимально топорно: вырезал из рассказа все технические описания и складывал их в один файл, группируя по темам. Прямую речь, разговорные вставки и короткие лирические отступления оставлял как есть — модель сама их проигнорирует. Правда, иногда приходилось немного дописывать: отдельные детали в оригинале были разбросаны и без контекста стали бы выглядеть как случайный набор слов. Но подобного было немного.
Сначала я работал с русским переводом, но потом подумал, что это не лучший вариант.
Во‑первых, оригинал на немецком даст более чистый результат — без искажений, которые неизбежно появляются при художественной интерпретации. Во‑вторых, в отличие от перевода Соломона Апта, оригинал уже перешел в общественное достояние и не охраняется авторским правом, так что с ним можно легально творить все, что душе угодно. И хотя вряд ли кто‑то предъявил бы мне за использование чужого перевода, мне было спокойнее иметь дело с оригиналом, помня, что перевод тоже является чьим‑то интеллектуальным трудом.
Поэтому я решил сначала собрать технический документ на немецком, а уже затем перевести его на русский с помощью LLM. Заодно было интересно сравнить термины машины и Соломона Константиновича. Чей перевод лучше подойдет для техдокументации?
Первый подход к машине
Сырой исходник готов — из 66 КБ рассказа остались только восемь. Теперь можно было скармливать его машине, чтобы она на его основе подготовила первую версию документа.
Этап важный: от него напрямую зависит, насколько вменяемым получится результат. Просто прикрепить файл и написать в чат «сделай мне техническую документацию» — идея так себе. На выходе, скорее всего, получится трудный для чтения и чрезмерно структурированный текст.
Кстати, когда я экспериментировал с вариантом на русском, именно так и получилось — документ вышел похожим на гостовый экспонат в плохом смысле этого слова.
Поэтому без нормального промпта было не обойтись. При этом тащить в запрос целый стайлгайд я посчитал избыточным — достаточно было обозначить ключевые требования на верхнем уровне. Остальное планировал довести уже на этапе редактуры: так и проще, и быстрее.
Для задачи я выбрал самую продвинутую модель с увеличенным временем рассуждения.
В оригинальном рассказе Кафка никак не называет аппарат. Для документации это неудобно, поэтому я придумал ему имя — «Механический писарь».
С одной стороны, в нем есть легкий архаический оттенок — аппарат все‑таки из начала XX века.
С другой стороны, слово «писарь» отсылает к мему, который однажды попал в среду техписов Positive Technologies и там закрепился — уже как кастомная реакция в корпоративном мессенджере.
Промпт
ЗАДАЧА
------
Ты — технический писатель. Subject Matter Experts предоставили тебе исходники. Исходники описывают аппарат (назовем его "Механический писарь"), его устройство и алгоритм действия. Нужно переработать текст так, чтобы получилась техническая документация на языке исходника. В ходе подготовки документа следуй предложенным правилам и структуре.
ПРАВИЛА
-------
1. Разделы документа не нумеруй. Выходной формат — Markdown.
2. Стиль языка — нейтральный, технический, но дружелюбный пользователю, без канцеляризмов и обилия страдательного залога. В остальном старайся по максимуму сохранять исходные формулировки и фразы. Придерживайся единой терминологии.
3. Не дублируй информацию между разделами. При необходимости оформи перекрестные ссылки в текстовом виде.
4. Не используй лексику на английском языке.
5. Не используй оценочную лексику и слова, которые можно расстолковать по-разному.
СТРУКТУРА ДОКУМЕНТА
-------------------
# {Название аппарата} — {Название типа документа}
{Определение аппарата, определение документа и его аудитории}
# {Как устроен аппарат}
{Архитектура аппарата в общих чертах}
{Подзаголовок. Часть аппарата 1}
{Описание части 1 аппарата}
{Подзаголовок. Часть аппарата 2}
{Описание части 2 аппарата}
{Подзаголовок. Часть аппарата 3}
{Описание части 3 аппарата}
# {Алгоритм работы аппарата}
{Нумерованный одноуровневый список. Каждый элемент списка должен быть составлен в изъявительном наклонении. Предпочтительная формула: субъект-объект-действие. В списке до 10 пунктов включительно. Если получается больше — сгруппируй пункты или добавь второй уровень.}
# {Подготовка аппарата к работе}
{Что нужно сделать перед тем, для чего аппарат собственно предназначен. Нумерованный одноуровневый список шагов в повелительном наклонении. Список не должен включать в себя шаги по техобслуживанию — для этого есть отдельный раздел.}
# {Запуск аппарата}
{Что нужно сделать для запуска аппарата. Нумерованный одноуровневый список шагов в повелительном наклонении}
# {Техническое обслуживание аппарата}
{В виде простых абзацев}
# {Устранение неисправностей}
{В виде таблицы со столбцами “Проблема”-”Причина”-”Устранение”}
# {Ревизии аппарата}
{В виде таблицы. Каждая строка — описание версии (ревизии), что было изменено}
ИСХОДНИКИ
---------
// Сюда я вставил подготовленный сырой исходник //
Скальпель редактора
Модель поскрипела несколько минут и выдала результат. На первый взгляд он показался вполне вменяемым. Исходный текст аккуратно разложился по заданной структуре, предложения стали короче и лучше легли в формат технического документа. Заодно осовременилась и орфография. Кафка умер до реформы правописания 1996 года, поэтому оригинал был написан по старым правилам. Модель без проблем заменила слова вроде daß, muß и Abflußrohr на современные dass, muss и Abflussrohr.
Но без ручной редактуры все равно не обошлось. Часть правок была чисто технической и решалась быстро. Например, информация о том, что аппарат работает двенадцать часов, почему‑то оказалась в вводном разделе, хотя уже была на своем месте в описании алгоритма. Этот нелогичный дубль я просто убрал.
Основная проблема была в стилистическом конфликте. В промпте я просил LLM сделать документацию дружелюбной пользователю и использовать нейтральную лексику, но в остальном задействовать выражения из оригинала. На практике модель фанатела по оригиналу.
Язык Кафки в этом рассказе удивительно пригоден для технической документации: он уже наполовину инженерный, структурно выверенный, с четкими причинно‑следственными связями. Но, будучи все‑таки художественной литературой, он не лишен бытовых обозначений технических реалий, архаичной и даже философской лексики.
И вот здесь мне уже понадобился хирургический скальпель, чтобы подобную лексику онейтралить и осовременить.
Пример: в нескольких местах модель сохранила слово Leib — в зависимости от контекста оно может означать «плоть» или «живот». Для технического руководства это слово было бы слишком окрашенным, поэтому по всему документу я заменил его на нейтральное Körper («тело»).
При всем при этом названия частей аппарата мне хотелось сохранить в оригинальном виде, потому что здесь они работают как имена собственные. Например, Egge («борона») — это не просто нарицательное слово, а название конкретного узла аппарата. В этом плане модель все сделала правильно.
Для машинной редактуры я поставил отдельную задачу другой LLM. Я попросил ее не переписывать файл самостоятельно, а прислать замечания и комментарии. Так я мог посмотреть, что именно ИИ предлагает изменить, и вносить правки точечно, а не принимать все подряд.
Наконец, оставалась небольшая дыра в логике документа. У Кафки сказано, что аппарат настраивают по чертежам, но никаких подробных инструкций, разумеется, не дается. Поэтому в подходящем месте я добавил ссылку на отдельное руководство по настройке чертежника. Этого документа не существует, но для правдоподобия инструкции я пошел на это допущение.
Лишнее колесо на схеме
Текст вроде как готов, что дальше? Хорошо бы добавить рисунки. В Positive Technologies мы в основном описываем ПО, и основную массу изображений составляют скриншоты. Но в моем эксперименте речь шла про «железку». Поэтому я решил добавить ее схему. Тем более что исходного текста для этого было достаточно: в начале документа как раз описывается устройство аппарата, из каких основных частей он состоит, для чего они нужны и как взаимодействуют друг с другом. Но одно дело читать это по абзацам, и совсем другое — сразу видеть общую схему на картинке.
Задачу по отрисовке схемы я тоже отдал языковой модели. На выходе важно было получить редактируемый вариант, который, как и текст, можно довести руками. Поэтому мне не подходили ни рисунок в фотореалистичном стиле, ни представление нейрохудожника — я все‑таки делаю техническую документацию, а не глянцевый журнал. Полноценный чертеж тоже был не нужен: для него в исходнике недостаточно данных, да и сам документ рассчитан на операторов аппарата, а не на тех, кто будет его ремонтировать.
Наиболее подходящим форматом был SVG. Он векторный, поэтому не пикселизуется при увеличении масштаба, легко встраивается и в веб‑страницу, и в PDF. Но главное то, что SVG — обычный XML, который можно править вручную в любом текстовом редакторе. То есть модель могла бы сгенерировать основу, которую я бы потом довел до ума.
Я перепробовал ChatGPT, Claude и Gemini. И у всех результат на старте получился неудовлетворительным: где‑то лестница висела в воздухе, где‑то отдельные компоненты не отрисовывались, а просто перечислялись внутри контейнера. И во всех вариантах были проблемы с выносками: подписи стояли криво относительно объектов и были не выровнены.
Claude выдал самую детализированную схему.
ChatGPT, наоборот, нарисовал все максимально упрощенно (но даже в таком варианте умудрился накосячить).
Дальше я пошел по привычному пути: в чате просил добавить недостающие элементы и поправить конкретные места — но довольно быстро уперся в несовершенства модели.
Несмотря на явные указания править только отдельные части, она постоянно норовила затронуть что‑то еще.
Исправляешь одну ошибку — получаешь новую в другом месте. Здесь, например, ИИ неожиданно пририсовал сливную трубу туда, где по логике ее быть не может.
Когда диаграмма дошла до более‑менее приемлемого состояния, я перестал мучить модель и приступил к ручной правке SVG. Подровнял элементы, поправил размеры и отступы, скорректировал подписи и линии выносок. Особенно следил за тем, чтобы схема нормально пережила локализацию: например, линию выноски лучше не привязывать к концу текстовой строки, потому что в другом языке подпись почти наверняка окажется длиннее или короче.
В результате получилась такая схема:
Итог меня почти устроил. Почти, потому что яма (Grube) выглядит так, будто находится под землей, и изящно решить я это сходу не смог. Впрочем, для такой схемы это уже допустимая условность.
Был и еще один момент — с колесом (Rad). В рассказе оно упоминается лишь вскользь. В версии Claude оно появилось, но без пояснения его назначение оставалось бы непонятным, а опереться тут было не на что. Поэтому колесо я в схему не включил.
Большой взрыв отменяется: от верстки до эмодзи
Итак, документ был готов: вычитан с помощью искусственного и человеческого интеллекта, снабжен наглядной иллюстрацией и уже выглядел как полноценное техническое руководство. Оставалось все это красиво и грамотно упаковать, чтобы доставить до «пользователя».
Можно было просто скомпоновать PDF или DOCX. Но мне не хотелось превращать результат в банальный файл с документацией: это казалось слишком статичным и старомодным решением. Поэтому я решил сделать веб‑версию документа и выложить ее в сеть. Тем более мой регистратор недавно подарил мне доменное имя на выбор в зоне .site на год — почему бы не воспользоваться предложением?
Требования к сайту у меня были простыми:
Одна страница. Документ небольшой, поэтому дробить его на несколько HTML‑файлов нет смысла. Куда лучше собрать все в одном месте и дать читателю нормальное оглавление без необходимости отправлять лишние запросы к веб‑серверу. Любые нажатия внутри сайта тоже должны происходить без перезагрузки страницы.
Светлая и темная темы. Выбор темы для современного веб‑документа — маст‑хэв. Тем более здесь: причинять страдания предназначен сам аппарат, а не руководство по его эксплуатации. Поэтому ночью оно не должно пытать оператора ярким белым светом с экрана. Дополнительно нужно не забыть про схему аппарата: ее цвета должны адаптироваться при смене темы, чтобы все ее надписи и элементы выглядели различимо и приятно как на светлом, так и на темном фоне.
Адаптация под мобильные устройства. Верстку нужно адаптировать под смартфоны: пользователь документа может читать его не только за столом, но и в полевых условиях — рядом с самим аппаратом. Носить с собой ноутбук там не слишком удобно, особенно если придется подниматься с ним по прикладному трапу.
Переключатель языков. У документа будут немецкая и русская версии, а значит, нужно дать возможность переключаться между ними по кнопке, а не заставлять пользователя колдовать с URL.
Минимальная автоматизация. Страница должна учитывать параметры операционной системы и браузера при выборе языка и темы по умолчанию. А слова в тексте — переноситься между строчками по слогам. Казалось бы, мелочи, но из таких мелочей складывается общее пользовательское впечатление о справке.
Можно было самостоятельно написать страницу с нуля. Но сейчас с подобными задачами куда быстрее и эффективнее справляются LLM. Поэтому я пошел по пути вайбкодинга.
Я не стал сразу вываливать на модель весь список требований, а выбрал стратегию постепенного усложнения. Сначала попросил собрать общий макет страницы. Потом отдельно доработал меню — оно же оглавление документа. Затем занялся заголовками, переключателями, поведением на мобильных экранах, темами и стилями. Так мне было проще контролировать результат на каждом этапе. Если модель «уезжала» не туда, я замечал это сразу и просил поправить.
Главное в таком процессе — достаточно ясно представлять, что именно должно получиться. Абстрактные запросы вроде «сделай простой минималистичный дизайн» быстро показали свою бесполезность. В первом варианте сайт получился перегруженным деталями и заметно тормозил при взаимодействии. Модель поняла «минимализм» по‑своему и выдала дизайн в духе жидкого стекла в охристых оттенках.
После этого я пошел от меньшего к большему и стал формулировать требования точнее: добавь воздуха, поменяй цвет, увеличь отступ, выровняй элемент.
Так я спокойно поднимался по лесенке вайбкодинга, вместо того чтобы сначала получить от модели большой взрыв, а потом долго и мучительно разгребать его последствия. Это, пожалуй, главный практический вывод из этого этапа: LLM неплохо помогает писать код, но ей все равно нужен архнадзор. Просто теперь редактировать приходится не текст, а интерфейс.
Когда веб‑страница была готова, стало понятно, что документу все еще не хватает визуальных акцентов. Несмотря на таблицы, схему и списки, внутри оставалось много сплошного текста. В технической документации это опасно: важные фрагменты легко растворяются в общем массиве, особенно если пользователь читает не ради удовольствия, а потому что где‑то рядом уже скрипит зубчатый механизм.
Поэтому я добавил несколько информационных блоков. Два из них работают как примечания, а один выделяет фрагмент, требующий особого внимания. Его я оформил как предупреждение в красном блоке. Это помогает быстро отделить обычное описание от информации, которую лучше не пропускать.
Заодно я вставил эмодзи рядом с заголовками разделов. В своих настоящих руководствах я подобных украшательств не позволяю: все‑таки аудитория у компании серьезная, кибербез. Но здесь эмодзи сделали свое дело. С одной стороны, они помогают быстрее ориентироваться в структуре страницы. С другой — добавляют нужную долю абсурда. Ведь речь идет о современной веб‑документации для кафкианского аппарата. Если где‑то и уместны цветные рисованные иконочки, то именно здесь.
Посмотреть сам сайт можно по ссылке.
Слив локализации в яму и перевод на русский
Страница для сайта была готова — оставалось перевести ее на русский. Все‑таки для большинства моих читателей именно русский будет основным языком.
Переводить, как я уже писал выше, должен был искусственный интеллект. Но сначала нужно было вынести все локализуемые строки в отдельный файл. Именно этот файл потом и отправился бы модели на перевод.
Так безопаснее: модель работает только с текстом и не трогает верстку, логику страницы и служебный код. А мне проще контролировать результат, править отдельные строки и переиспользовать ключи там, где это нужно.
В этот же файл нужно было вынести и текстовые метки с диаграммы. В этом как раз одно из преимуществ SVG: диаграмму не пришлось дублировать отдельным файлом для каждого языка. Достаточно было оставить саму графику общей, а подписи подставлять из локализационного файла.
Я не стал продумывать, как именно технически отделить локализацию от кода самой страницы, а просто поставил эту задачу той же модели, которая помогала мне собирать сайт. И она справилась. Структура получилась простой: в HTML остались только ссылки на локализационные ключи, а сами тексты переехали в языковые файлы.
Почти все тексты. В index.html осталась только одна обычная строка — содержимое тега <title>. Формально его значение тоже вынесено: после загрузки страницы скрипт подставляет заголовок из текущего языкового файла. Но сам тег <title> я не стал оставлять пустым. Он нужен как безопасный начальный fallback до выполнения JavaScript: его читают вкладки браузера, история, закладки, предпросмотры ссылок, а еще поисковые системы и разные парсеры, которые могут смотреть исходный HTML, не дожидаясь выполнения скриптов. Поэтому нормально было оставить в исходнике один дефолтный заголовок, а затем заменять его через JavaScript. Пустой <title>, отсутствие <title> и тем более мусор в этом месте были бы хуже.
Остальные строки работают уже по общей схеме. Покажу на примере подписи ямы (Grube) на SVG‑диаграмме. В файле index.html эта подпись живет в одном из элементов <text>. Раньше текст подписи записывался внутрь этого тега. После выноса локализации строка была перенесена в de-DE.js, а в атрибуте data-i18n осталась ссылка на ключ:
<!DOCTYPE html> <html lang="ru"> <head> ... <script src="./locales/ru-RU.js"></script> <script src="./locales/de-DE.js"></script> ... </head> <body> ... <svg class="device-diagram" ...> ... <text ... data-i18n="content.construction.diagramWastePit"></text> ... </svg> ... </body> </html>
А так выглядит сам ключ content.construction.diagramWastePit в файле de-DE.js:
window.__DOC_LOCALES = window.__DOC_LOCALES || {}; window.__DOC_LOCALES.de = { ... content: { construction: { ... diagramWastePit: "Grube" }, ... } };
Но один важный момент модель все‑таки не учла: она разбила некоторые предложения на несколько ключей из‑за ссылок внутри текста. Например, если в середине предложения стоит ссылка на другой раздел, модель пыталась вынести начало предложения в один ключ, текст ссылки — в другой, а конец — в третий.
bed: { noteHtml1: "Zur Funktion der Watte im Betrieb des Apparats siehe Abschnitt ", noteHtml2: "Betriebsablauf", noteHtml3: ".", },
Для локализации это очень плохая идея. Предложение должно храниться в одном ключе, потому что в разных языках порядок слов может быть разным. Иначе перевод легко ломается: в одном языке ссылка окажется в середине фразы, в другом ей место в конце, а в третьем всю конструкцию придется перестраивать. Если текст заранее нарезан на куски, нормально переставить его уже нельзя.
Пришлось попросить модель переделать структуру. От расщепа я избавился, но теги ссылок попали внутрь локализационных строк.
bed: { noteHtml: "Zur Funktion der Watte im Betrieb des Apparats siehe Abschnitt <a class=\"xref\" href=\"#algorithm\">Betriebsablauf</a>.", },
Это не идеальное решение: смешивать текст и HTML обычно не хочется. Но ссылок было мало, сами они простые, так что конкретно для этого сайта я решил не усложнять локализационный механизм. В более серьезных проектах такие места нужно обрабатывать аккуратнее и гибче — именно так мы поступаем при локализации интерфейсных текстов наших продуктов.
Когда файл de-DE.js был готов, я отправил его модели на перевод. Затем по уже привычной схеме отдал на редактуру русский файл ru-RU.js: часть проблем нашла модель, часть я поправил руками.
После редактуры русскую версию оставалось оттипографить. С кавычками и тире все уже было в порядке, поэтому нужно было избавиться от висячих предлогов. Для этого я попросил ИИ аккуратно расставить неразрывные пробелы после коротких предлогов, союзов и частиц, а заодно после чисел в цифровой форме. Так строка не заканчивается одиноким „в“ или „на“, а число не отрывается от единицы измерения. Маленькие правки, но они влияют на общую читаемость.
Заодно я точечно поправил и файл на немецком: для типографики на этом языке не характерна проблема висячих предлогов в русском понимании, но числовые связки «2 m» и «24 Stunden» тоже не стоит разрывать переносом строки.
solomon apt update: сборка глоссария с переводчиком
Наконец, оставалось собрать глоссарий. В веб‑версию он не попадал, но был нужен как контрольный инструмент: проверить, все ли понятия названы корректно, нет ли расхождений в терминах и соблюдается ли единообразие в разных частях документа. А еще на глоссарии было удобно проверить то, о чем я говорил в начале статьи: где термины, выбранные ИИ, совпадают с вариантами из русского перевода Соломона Апта, а где расходятся.
Глоссарий я, разумеется, тоже поручил языковой модели. Для этого загрузил два готовых файла локализации, ru-RU.js и de-DE.js, и попросил составить CSV‑файл со столбцами:
Термин (de);Термин (ru);Определение
Почему именно CSV? По той же причине, что и раньше: это простой редактируемый формат. Если в результате обнаружится ошибка или захочется что‑то добавить, файл можно открыть в простом блокноте или любой программе для работы с таблицами типа Microsoft Excel или OpenOffice Calc.
Модель собрала глоссарий из 25 терминов. Результат получился вполне рабочим: ключевые понятия были выделены. Не хватало разве что термина Napf. Казалось бы, миска и миска, но даже ее можно перевести по‑разному: чаша, чашка, котелок. Поэтому для полноты я добавил этот термин вручную.
Готовый CSV‑файл я использовал для проверки единообразия терминологии в документе. Расхождения были минимальными и в основном касались подписей на схеме. Видимо, сказалось то, что текстовые выноски существуют отдельно, короткими фрагментами и почти без контекста. В таких условиях модель иногда выбирала не тот вариант, который был нужен для документа. Эти места я поправил вручную в файле русской локализации.
Затем я добавил в CSV еще один столбец — с вариантами терминов из перевода Соломона Апта. Так стало возможно сравнить решения ИИ и переводчика.
Термин (de) | Термин (ИИ) | Термин (Апт) | Определение |
Mechanischer Schreiber | механический писарь | — | Стационарный аппарат для исполнения судебных приговоров путем нанесения текста нарушенного предписания на тело осужденного |
Apparat | аппарат | аппарат | Общее наименование всей установки и ее механизмов |
Bett | ложе | лежак | Нижняя часть аппарата, на которой размещается и фиксируется осужденный |
Egge | борона | борона | Подвешенная средняя часть аппарата с иглами, которая наносит надпись на тело осужденного |
Zeichner | чертежник | разметчик | Верхняя часть аппарата с зубчатым механизмом, задающая движение бороны по чертежу приговора |
Verurteilter | осужденный | осужденный | Лицо, над которым исполняется приговор с помощью аппарата |
Gebot | предписание | заповедь | Формулировка требования, нарушение которого подлежит наказанию |
Urteil | приговор | приговор | Содержание судебного решения, исполняемого аппаратом |
Räderwerk | зубчатый механизм | система шестерен | Совокупность шестерен и связанных деталей, управляющих движением бороны |
Zeichnung | чертеж | чертеж | Схема, по которой настраивается зубчатый механизм под конкретный приговор |
Deckel | кожух | капот | Защитное покрытие верхней части аппарата от внешних воздействий |
Stahlseil | стальной трос | стальной трос | Элемент подвеса бороны, который при натяжении становится жестким |
Messingstange | латунная штанга | латунная штанга | Вертикальный соединительный элемент между ложем и чертежником |
Batterie | батарея | батарея | Источник электрического питания аппарата |
Leiter | лестница | трап | Средство доступа оператора к верхней части аппарата |
präparierte Watte | подготовленная вата | (препарированная) вата | Специально обработанный слой ваты на ложе, который смещает тело и останавливает кровотечение |
Filzstumpf | войлочный кляп | войлочный шпенек | Регулируемый элемент у изголовья ложа для подавления крика и предотвращения прикусывания языка |
Riemen | ремень | ремень | Фиксирующий элемент для рук, ног и шеи осужденного |
Napf | миска | миска | Посуда, в которой подается рисовая каша |
Reisbrei | рисовая каша | рисовая каша | Пища, которую подают осужденному во время цикла работы аппарата |
lange Nadeln | длинные иглы | длинные зубья | Иглы бороны, непосредственно наносящие надпись |
kurze Nadeln | короткие иглы | короткие зубья | Иглы бороны, подающие воду для смывания крови и сохранения читаемости надписи |
Abflussrohr | сливная труба | сточная труба | Трубопровод для отвода смеси воды и крови в яму |
Grube | яма | яма | Нижняя приемная часть, куда попадают жидкость, вата и тело осужденного |
Kurbel | рукоятка | рубильник | Коммутационный элемент для отключения чертежника |
Zieraten | орнаменты | узоры | Декоративные элементы, окружающие основную надпись на теле осужденного |
В целом видно, что большая часть различий находится в зоне вкуса и редакторского выбора. Например, для Bett можно было выбрать и «лежак», и «ложе»: оба слова применимы в техническом контексте, просто дают немного разный оттенок. «Лежак» звучит предметнее и бытовее, «ложе» — суше и технически строже.
В некоторых случаях мне ближе варианты Апта. Например, Leiter как «трап» выглядит удачнее, чем «лестница»: слово точнее попадает в технический регистр. То же с Kurbel: «рубильник» в данном контексте звучит убедительнее, чем нейтральная «рукоятка».
Но есть и обратные примеры. Для Gebot более правильным для техдоки вариантом мне показалось «предписание», а не «заповедь»: в руководстве по эксплуатации «предписание» лучше работает как термин, а «заповедь» слишком явно тянет за собой религиозный оттенок. С Nadeln тоже показался удачнее вариант ИИ: «иглы», а не «зубья». У Соломона Константиновича здесь получилось странно: почему он выбрал «зубья», я так и не понял. В оригинале это именно иглы, и по прямому значению слова, и по логике работы аппарата. Причем в конце рассказа Апт все‑таки переводит это слово как «иглы»:
Но вот не сработало и последнее — тело не отделялось от длинных игл.
Und nun versagte noch das Letzte, der Körper löste sich von den Nadeln nicht.
На этом техническая часть эксперимента фактически закончилась. У меня был готовый документ, веб‑версия, локализация, схема и глоссарий, который помог проверить терминологию напоследок. Дальше оставалось уже не собирать новые артефакты, а разобраться, что весь этот путь говорит о работе технического писателя с ИИ.
Заключение
Оказавшись на странном стыке философской притчи из начала прошлого века, технической редактуры и нейросетей, я прошел почти весь путь, который обычно проходит техпис, и даже чуточку больше. Я разобрался в предмете, собрал факты, выстроил структуру, написал текст, сделал схему, подготовил веб‑версию, добавил перевод и глоссарий. Практически на всех этих этапах я задействовал большие языковые модели. Однако эксперимент не свелся к очередному тексту, сгенерированному иишкой.
Вообще, здесь можно было бы написать пространный вывод о том, что ИИ не может полностью заменить голову технического писателя. Но это довольно очевидно, и мысль эта не свежа. Вы и сами могли убедиться в этом по тому, как много мне приходилось править после большой языковой модели. Поэтому на всех отрезках пути было важно сохранять возможность простого и удобного редактирования любой нейросетевой выдачи: текста, схемы, кода, локализации, глоссария. Правильный формат оказался важнее самой умной модели.
Из этого вытекают два практических вывода про работу с ИИ. Первый: нужны границы. Каждый раз, когда я давал модели слишком много свободы, она начинала чудить, ошибаться или упускать важные детали. Поэтому ей нужно не просто ставить задачу, а задавать коридор: исходник, структуру, формат результата, ограничения на правки. Второй: нужна декомпозиция. Выдавать всю задачу целиком в одном промпте оказалось плохой идеей. Лучше разбивать работу на небольшие шаги и контролировать результат на каждом из них, вручную или с помощью других моделей.
Но по‑настоящему меня удивил не ИИ, а сам материал. Кафкианский аппарат вдруг оказался очень удобным объектом для экспериментов с техдокументацией. Когда технический писатель описывает привычные программы или устройства, часть пробелов он может просто не заметить: будучи таким же пользователем, он достраивает недостающее из собственного опыта. А в случае со странным механическим аппаратом такие пустоты заполнить нечем: у автора и читателя нет готового представления о подобных агрегатах. Тут сразу всплывают любые неясности в структуре, терминах, логике работы или иллюстрации. В общем, необычный материал помогает освежить взгляд на техническую документацию и снова увидеть, зачем ей нужны последовательность, однозначная терминология и проверяемая структура.
Самый неочевидный итог эксперимента, кажется, лежит уже на стыке лингвистики и психологии. Переведя текст Кафки на сухой, выверенный язык техдокументации, я столкнулся с парадоксальным эффектом: нейтральная подача совсем не сгладила сюрреалистичность механизма. Наоборот, чем спокойнее текст описывает взаимодействие игл, шестеренок и войлочного шпенька, чем аккуратнее выстроены разделы и чем больше в интерфейсе привычной заботы о пользователе, тем сильнее проступает абсурдность самого объекта.
Для технического специалиста это хорошая иллюстрация того, как формат управляет восприятием. Иногда именно стерильная, отстраненная точность технического языка обнажает суть происходящего сильнее любых художественных приемов. Даже веселые эмодзи рядом с заголовками в итоге не смягчили эффект, а только подчеркнули странный контраст между современной веб‑документацией и холодной машинной жестокостью аппарата.
Здесь легко вспомнить концепцию «банальности зла»: самые чудовищные вещи часто совершаются не под раскаты грома, а буднично, с регламентами, формулярами, инструкциями и удобной адаптивной версткой. В моем эксперименте это ощущение возникло почти само собой, хотя начиналось все как шутка про Кафку, техдок и нейросети.
И все же главный профессиональный вывод остается простым: даже кафкианский аппарат можно описать современно и понятно, если не принимать первый сгенерированный нейросетью вариант за готовую документацию. А если это верно для механической машины из кошмарной притчи, то разве мы можем позволить себе менее ясные инструкции там, где речь идет о настоящих системах, кибербезопасности и защите от вполне реальных хакеров?
Вопрос, конечно, риторический.
Если вы хотите самостоятельно изучить итоговый документ целиком, он доступен по ссылке. А с исходным кодом проекта можно ознакомиться в репозитории GitHub.
Изображение на обложке сгенерировано нейросетью на основе архивной фотографии Франца Кафки.
