Ясный технический текст: действие, условие и проверка

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

В этой практике я соединяю принципы ясного языка, технического письма ASD-STE100 и подход Уильяма Зинссера. Это редакционная основа, а не заявление о соответствии русских текстов английскому стандарту. Его словарь и грамматические ограничения нельзя переносить на русский механически.

Начните с задачи читателя

Перед редактированием ответьте на три вопроса: кому нужен текст, что человек должен понять и что сможет сделать после чтения. Если инструкция рассчитана на стажёра, название инструмента нужно объяснить. Опытному специалисту достаточно короткой памятки.

Вместо «Посмотрите запрос в DevTools» напишите путь для выбранного браузера: «В Chrome на Windows нажмите F12. Откройте вкладку Network. Повторите действие на странице и найдите запрос». Затем укажите, какое поле или значение нужно проверить. Названия элементов могут меняться; сверяйте их с используемой версией.

Назовите действие и исполнителя

Фраза «Осуществляется проверка настроек» не говорит, кто проверяет и что именно. Лучше: «Перед запуском администратор проверяет адрес сервиса и права учётной записи». Если это шаг инструкции, используйте прямую команду: «Проверьте адрес сервиса».

Одна инструкция обычно содержит одно действие. Условие, которое меняет порядок работы, ставьте перед действием: «Если запрос завершился ошибкой, сохраните её код. Затем проверьте журнал». Не убирайте условие ради короткой фразы.

Сохраняйте постоянные термины

Выберите одно название для одной сущности. Если в интерфейсе написано «Переговорная», не называйте тот же объект то комнатой, то ресурсом, то помещением в соседних шагах. Поясните технический термин при первом употреблении и используйте его дальше последовательно.

Ссылка должна называть документ или ожидаемый результат. «Документация API» полезнее, чем «здесь». Код, путь, идентификатор и имя кнопки сохраняйте точно. Их нельзя переписывать ради красивого языка.

Разделите роль и результат

В описании опыта покажите, что сделали лично, что выполнила команда и что ещё находится в работе. «Я уточнил требования и участвовал в изменении архитектуры. Команда реализовала основные процессы» сохраняет границы вклада.

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

Учитывайте перевод

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

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

Проверьте текст на действии

Дайте инструкцию человеку, который не знает задачу. Попросите найти нужный шаг и объяснить результат. Запишите вопросы. Если человек понял слова, но не знает, что делать, уточните содержание, а не только сократите предложения.

У описания проекта своя проверка: может ли читатель назвать задачу, вашу роль и статус без дополнительных пояснений? Если нет, исправьте эти части первыми.

Источники

Основа редакционных правил этого сайта — предоставленное автором руководство «Ясность как рабочий инструмент» от 3 октября 2026 года.