Simple English
Переписывает текст по правилам ASD-STE100 Simplified Technical English.
Метаданные навыка
| Источник | Опциональный — установите командой hermes skills install official/creative/simple-english |
| Путь | optional-skills/creative/simple-english |
| Версия | 1.2.0 |
| Автор | AminBlg (https://github.com/AminBlg/SimpleEnglish), портировано Hermes Agent |
| Лицензия | MIT |
| Платформы | linux, macos, windows |
| Теги | writing, documentation, ste, asd-ste100, technical-writing, editing, anti-ai-slop |
| Связанные навыки | humanizer |
Справочник: полный SKILL.md
Далее приведено полное определение навыка, которое Hermes загружает при его активации. Это инструкции, которые видит агент, когда навык включён.
Simple English: пишите как авиационное техническое руководство
Пишите технический текст по правилам ASD-STE100 Simplified Technical English. STE — это контролируемый язык, который производители авиационной и оборонной техники используют для документации по обслуживанию. Правила существуют для того, чтобы уставший читатель, для которого английский не родной, не мог неправильно понять инструкцию. Заодно они убирают типичные признаки текста, сгенерированного ИИ: длинные предложения, чередование синонимов, оговорки, слова-паразиты и декоративные обороты.
Пишите для этого уставшего читателя. Каждое предложение должно быть понятно с одного прочтения.
Как использовать навык в Hermes
Текст обычно поступает одним из трёх способов:
- Прямо в сообщении. Пользователь вставляет текст в сообщение. Перепишите его на месте и верните результат в ответе.
- Файл. Пользователь указывает на файл (README, runbook, страницу документации). Загрузите его через
read_file, затем используйтеpatchдля точечной правки отдельных разделов илиwrite_fileдля полной переписки. Никогда не трогайте блоки кода, идентификаторы и цитируемые тексты ошибок (см. раздел «Неприкосновенное»). - Режим проверки. Пользователь просит проверить текст на соответствие STE, а не переписать его. Сообщайте о каждом нарушении в формате: номер правила + проблемный текст + вариант, приведённый в соответствие, — используя
references/checklist.md.
Этот навык отличается от humanizer: humanizer возвращает тексту естественное человеческое звучание, а simple-english применяет контролируемый язык для технических инструкций. Для документации, runbook’ов и сообщений об ошибках используйте этот навык. Для постов в блог, эссе и личных текстов — humanizer. Не применяйте оба навыка к одному и тому же тексту.
Ваша задача
Когда вас просят написать или переписать технический текст, выполните следующее:
- Выберите режим (прагматичный или строгий — см. ниже).
- Классифицируйте каждый фрагмент как процедурный или описательный. От этого зависят все остальные правила.
- Определитесь со словарём до начала работы. В строгом режиме используйте
make sure thatдля понятия check/verify/confirm/ensure — словарь отклоняет все четыре как глаголы. В прагматичном режиме выберите один вариант и придерживайтесь его. Выберите ОДНО существительное для config/settings (оба варианта — допустимые технические существительные, выберите один и не меняйте его). Не используйте для этих понятий другие слова во всём документе. - Примените правила из каталога ниже.
- Проведите самопроверку перед сдачей результата. Этот шаг обязателен.
- Никогда не трогайте код, идентификаторы, команды и цитируемые тексты ошибок (см. раздел «Неприкосновенное»).
Когда вас просят ПРОВЕРИТЬ текст, а не написать его, сообщайте о каждом нарушении в формате: номер правила, проблемный текст, приведённый в соответствие вариант. Ссылайтесь только на номера правил, которые есть в этом файле. Не приводите номера правил по памяти: нумерация неинтуитивна, и модели её выдумывают (проверено на практике — агент без этого файла сослался на «Правило 3.1: короткие предложения»; на деле Правило 3.1 касается форм глагола).
Два режима
| Режим | Когда применять | Что применять |
|---|---|---|
| Прагматичный (по умолчанию) | Документация, README, сообщения об ошибках — пользователю нужен понятный текст | Все структурные правила. Термины предметной области остаются («idempotent», «webhook»). |
| Строгий | Пользователь прямо называет STE, ASD-STE100 или соответствие стандарту | Структурные правила + полная словарная дисциплина; предупредите пользователя, что для полного соответствия нужен официальный словарь (бесплатно на asd-ste100.org). |
Шаг 1. Классифицируйте текст
| Процедурный (инструкции) | Описательный (объяснения) | |
|---|---|---|
| Цель | Сказать читателю, что делать | Объяснить, что это такое или как это работает |
| Форма глагола | Повелительное наклонение: «Install the pump» | Простое настоящее/прошедшее/будущее время |
| Лимит слов в предложении | 20 слов (Правило 5.1) | 25 слов (Правило 6.3) |
| Правило единицы | Одна инструкция на предложение (5.2) | Одна тема на абзац (6.5), максимум шесть предложений на абзац (6.6) |
Не смешивайте эти два типа в одном фрагменте. Раздел «Getting started» — процедурный. Раздел «Architecture» — описательный. Примечание внутри процедуры — тоже описательный текст (лимит 25 слов, без повелительного наклонения).
КАТАЛОГ ПРАВИЛ
53 правила в 9 разделах — пересказ ASD-STE100 Issue 9 с примерами из софтверной документации. Официальные формулировки — в бесплатном стандарте на asd-ste100.org.
Раздел 1 — Слова (Правила 1.1–1.14)
| Правило | Инструкция |
|---|---|
| 1.1 | Используйте только одобренные слова, технические существительные и технические глаголы. |
| 1.2 | Используйте одобренное слово только в той части речи, которая указана в словаре. |
| 1.3 | Используйте одобренное слово только в одобренном значении. |
| 1.4 | Используйте только одобренные формы глаголов и прилагательных. |
| 1.5 | Слова предметной области можно использовать как технические существительные («webhook», «commit», «endpoint»). |
| 1.6 | Неодобренное слово допустимо только если это техническое существительное или его часть. |
| 1.7 | Не используйте технические существительные как глаголы. |
| 1.8 | Используйте технические существительные, принятые в вашем проекте или отрасли. |
| 1.9 | Выбирая техническое существительное, выбирайте короткое и понятное. |
| 1.10 | Не используйте региональные, сленговые или жаргонные слова как технические существительные. |
| 1.11 | Один объект — одно название. Не называйте его «config» в одном месте и «settings» в другом. |
| 1.12 | Глаголы предметной области можно использовать как технические глаголы («deploy», «compile», «merge»). |
| 1.13 | Не используйте технические глаголы как существительные. |
| 1.14 | Используйте американское написание слов. |
В прагматичном режиме основную работу делают правила 1.5, 1.8 и 1.12: лексика вашей предметной области разрешена. Чаще всего агенты нарушают 1.7, 1.11 и 1.13.
Before: You can webhook the event, then do a deploy. After: Send the event to the webhook. Then deploy the service.
Раздел 2 — Составные существительные (Правила 2.1–2.2)
| Правило | Инструкция |
|---|---|
| 2.1 | Составные существительные должны состоять не более чем из трёх слов. |
| 2.2 | Если техническому существительному нужно больше трёх слов, один раз напишите его полностью, а затем используйте краткую форму или соедините части дефисом. |
Разбивайте длинные цепочки существительных предлогами (of, on, in, for):
Before: the connection pool timeout configuration value After: the timeout value for the connection pool
Раздел 3 — Глаголы (Правила 3.1–3.7)
| Правило | Инструкция |
|---|---|
| 3.1 | Используйте только те формы глагола, которые даёт словарь. |
| 3.2 | Используйте только: инфинитив, повелительное наклонение, простое настоящее, простое прошедшее, простое будущее время, причастие прошедшего времени в роли прилагательного. |
| 3.3 | Используйте причастие прошедшего времени только как прилагательное («the cached response»). |
| 3.4 | Не используйте вспомогательные глаголы для сложных конструкций. Никакого present perfect, никакого «is to be installed». |
| 3.5 | Форму на «-ing» используйте только как техническое существительное или его часть («logging», «the mounting bracket») — никогда как глагол. |
| 3.6 | Действительный залог. В описательном тексте страдательный залог допустим только если субъект действия неизвестен. |
| 3.7 | Описывайте действие глаголом, а не существительным («compress the file», а не «perform compression of the file»). |
Одобренные модальные глаголы: can, will, must. Запрещены: should, would, may, might, could (Правило 3.2). Стандарт отклоняет «could» даже в значении возможности: пишите «an explosion can occur», никогда не «could occur». Для «should»: требование превращается в «must», рекомендация формулируется как факт или удаляется вовсе. Для инструкций агентам это особенно важно — модели читают «should» как необязательное указание.
Before: The migration has completed and the table is being rebuilt. After: The migration is complete. The database rebuilds the table.
Before: The flag can be set in the config file, making restarts unnecessary. After: You can set the flag in the config file. Then a restart is not necessary.
Before: The temperature must be adjusted. After: Adjust the temperature.
Раздел 4 — Предложения (Правила 4.1–4.5)
| Правило | Инструкция |
|---|---|
| 4.1 | Пишите короткие и понятные предложения. |
| 4.2 | Не сокращайте предложения за счёт пропуска слов или использования сокращённых форм. Сохраняйте артикли, сохраняйте «that». |
| 4.3 | Для сложного текста используйте маркированный список. |
| 4.4 | Используйте связующие слова между предложениями на смежные темы («Then», «As a result»). |
| 4.5 | Ставьте перед существительным артикль (the, a, an) или указательное прилагательное (this, these), где это применимо. |
Правило 4.2 — это правило против чрезмерной сжатости. STE — это короткие предложения с полной грамматикой, а не телеграфный стиль:
Wrong shortening: Ensure file exists before running. STE: Make sure that the file exists before you run the command.
Раздел 5 — Процедурный текст (Правила 5.1–5.5)
| Правило | Инструкция |
|---|---|
| 5.1 | Не более 20 слов в предложении. Включая предупреждения (warnings) и предостережения (cautions). |
| 5.2 | Одна инструкция на предложение, если только два действия не выполняются одновременно. |
| 5.3 | Пишите инструкции в повелительном наклонении: «Run the migration». |
| 5.4 | Ставьте обязательное условие перед командой, разделяя их запятой: «If the build fails, read the log». |
| 5.5 | Примечания дают информацию, а не инструкции. На примечания распространяется лимит в 25 слов. |
Before: You’ll want to grab the API key from the dashboard before configuring the client, which you can do under Settings. After: Get the API key from the dashboard, under Settings. Then configure the client with this key.
Раздел 6 — Описательный текст (Правила 6.1–6.6)
| Правило | Инструкция |
|---|---|
| 6.1 | Подавайте информацию постепенно: один новый факт на предложение. |
| 6.2 | Используйте ключевые слова и фразы, чтобы придать тексту логическую структуру. |
| 6.3 | Не более 25 слов в предложении. |
| 6.4 | Группируйте связанную информацию в абзацы. |
| 6.5 | Одна тема на абзац. |
| 6.6 | Не более шести предложений в абзаце. |
В описательном тексте не используется повелительное наклонение. Описания объясняют, процедуры дают указания.
Раздел 7 — Инструкции по безопасности (Правила 7.1–7.3)
| Правило | Инструкция |
|---|---|
| 7.1 | Используйте слово, обозначающее уровень риска («WARNING» = травма, «CAUTION» = повреждение). |
| 7.2 | Начинайте с чёткой команды или условия. |
| 7.3 | Затем указывайте риск или возможный результат. |
Никогда не прячьте инструкцию после объяснения. Этот шаблон напрямую применим к разрушительным флагам CLI, необратимым миграциям и опасным опциям API.
Before: Note that data loss may occur in some circumstances if the destructive flag happens to be enabled when running against production.
After: CAUTION: Do not use the --force flag against production. The flag deletes rows that do not match the source.
Раздел 8 — Пунктуация и подсчёт слов (Правила 8.1–8.7)
| Правило | Инструкция |
|---|---|
| 8.1 | Разрешены все стандартные знаки препинания, кроме точки с запятой. Вместо неё пишите два отдельных предложения. |
| 8.2 | Используйте дефис для соединения слов, которые действуют как единое целое. |
| 8.3 | Скобки допустимы для ссылок, номеров пунктов, сокращений, форм множественного числа, пояснений, альтернатив. |
| 8.4 | В маркированном списке вводное двоеточие завершает предложение для целей подсчёта слов. |
| 8.5 | Текст в скобках считается одним словом. |
| 8.6 | Каждое из следующего считается одним словом: числа, числа с единицами измерения, сокращения, буквенно-цифровые идентификаторы, текст в кавычках, заголовки, метки, имена собственные. |
| 8.7 | Слово, написанное через дефис, считается одним словом. |
Правило 8.6 важно для софтверных текстов: sqlpipe run --config sqlpipe.yaml в обратных кавычках — это текст в кавычках, и он считается одним словом. Длинные идентификаторы не съедают лимит слов в предложении.
Раздел 9 — Практики письма (Правила 9.1–9.4, GR-1–GR-8)
| Правило | Инструкция |
|---|---|
| 9.1 | Если пословная замена не работает, перестройте предложение. |
| 9.2 | Используйте каждое одобренное слово правильно: в одобренном значении и в одобренной части речи. |
| 9.3 | Не составляйте фразовые глаголы («go down» → «decrease», «set up» → «install» или «configure»). |
| 9.4 | Придерживайтесь единого стиля и терминологии на протяжении всего документа. |
Общие рекомендации GR-1–GR-8: сохраняйте союз «that», аккуратно обращайтесь с «with», давайте местоимениям чёткий референт, предпочитайте «this + существительное» голому «this», избегайте ложных друзей переводчика, избегайте латинских сокращений, используйте инклюзивный язык и притяжательную форму с апострофом ставьте только тогда, когда уверены в её правильности (GR-8: если сомневаетесь — не используйте её, читателям, для которых английский не родной, она даётся тяжело).
GR-6 для софтверной документации: «e.g.» → «for example», «i.e.» → «that is», а «etc.» удаляйте — перечисляйте пункты явно или пишите «and more».
СЛОВАРНАЯ ДИСЦИПЛИНА
Официальный словарь (~900 одобренных слов, ~1200 запрещённых слов с альтернативами) защищён авторским правом ASD и здесь не приводится. Его механика работает и без него: одно слово, одно значение, одна часть речи.
Известные решения по частям речи — полезны как образцы:
| Слово | Решение |
|---|---|
| test, check, work | Только существительное. «Do a test», а не «test the pump». «Check that X» превращается в «make sure that X». |
| oil | Только техническое существительное (TN). Для глагола словарь даёт «lubricate»: «Lubricate the linkage with oil». |
| help | Только глагол. Для существительного словарь даёт «aid»: «with the aid of». |
| fall (существительное) | Отклонено. Для уменьшения значения используйте «decrease». FALL (глагол) используйте только для физического движения вниз под действием силы тяжести: «Make sure that the tools do not fall into the engine». |
| follow | Только в значении «следовать за» (to come after), никогда — «подчиняться». Пишите «obey the instructions». |
| above, below | Только для физического положения. Для границ значений пишите «more than», «less than». |
Лестница модальных глаголов
| Вы написали | STE пишет |
|---|---|
| should (требование) | must |
| should (рекомендация) | Удалите, либо сформулируйте как факт: «X is better because Y». |
| may / might / could (возможность) | can |
| may (разрешение) | can |
| would (гипотетическое) | Перестройте: «If X occurs, Y occurs». |
Замены «мусорных» слов на простые
Эта таблица составлена нами, а не взята из словаря ASD. Она сопоставляет слова, которыми злоупотребляет сгенерированная ИИ документация, с простыми заменами. Если слово не несёт факта, удаляйте его вместо замены.
| Мусорное слово | Пишите вместо |
|---|---|
| leverage, utilize | use |
| in order to | to |
| prior to | before |
| ensure | make sure that (строгий режим; в прагматичном режиме ensure допустим, если это ваш единственный выбранный глагол-проверка) |
| it is worth noting that | (удалить) |
| it’s important to, crucially | (удалить — сформулировать как факт) |
| simply, just, easily, seamlessly, effortlessly | (удалить) |
| robust, powerful, comprehensive, performant | (удалить или указать измеримое свойство) |
| functionality | function, feature |
| enables you to, allows you to | you can |
| is designed to, aims to | (удалить — сказать, что это делает) |
| facilitate | help, make possible |
| dive into, delve into | read, examine |
| when it comes to | for |
| in the event that | if |
| due to the fact that | because |
| as needed, as necessary | (указать условие) |
| and/or | выбрать один вариант или написать «X, or Y, or both» |
| e.g. / i.e. / etc. | for example / that is / (перечислить пункты) |
| gracefully handles | (сказать, что это делает: «retries three times, then stops») |
| out of the box | by default |
| under the hood | internally |
| blazingly fast, state-of-the-art | fast (указать число) / (удалить) |
| streamline | make simpler, make faster |
| plethora, myriad | many |
| addresses the issue, tackles | corrects the fault, removes the error |
Проверка на согласованность
Сводите чередующиеся синонимы к одному термину (Правила 1.11, 9.4). Два списка ниже работают по-разному.
Технические существительные — их нет в словаре. Выберите одно и придерживайтесь его (в обоих режимах):
- config / configuration / settings / options → выберите один вариант
Решения словаря — стандарт уже сделал выбор. Используйте одобренное слово (строгий режим); в прагматичном режиме выберите один вариант и придерживайтесь его:
| Вы написали | Статус в словаре | Используйте вместо |
|---|---|---|
| check (глагол) / verify / confirm / ensure | Все отклонены как глаголы | make sure that (строгий режим); выберите один вариант (прагматичный режим) |
| validate | Нет в словаре | Используйте как технический глагол (Правило 1.12) или замените на make sure that |
| delete / drop (глагол) / destroy | Все отклонены | erase (для данных), remove (для физических объектов); избегайте drop и destroy |
| remove | Одобренный глагол | Оставьте как есть |
| run / execute | Оба отклонены | operate вместо run, do вместо execute (строгий режим); выберите один вариант (прагматичный режим) |
| invoke / launch | Нет в словаре | Используйте как технические глаголы (Правило 1.12) |
| display (глагол) / render / present (глагол) | Все отклонены | show (одобренный глагол) |
| issue | Нет в словаре | Используйте как техническое существительное или замените на problem (одобрено) |
| failure | Отклонено в общем употреблении; одобрено как техническое существительное для потери работоспособности | Используйте только в значении ошибки работоспособности: «a failure of the pump» |
| error | Одобренное существительное | Оставьте как есть |
| problem | Одобренное существительное | Оставьте как есть |
Неприкосновенное
Это технические имена (Правила 1.5, 8.6). Оставляйте их без изменений, даже если они нарушают словарные правила:
- Блоки кода, инлайн-код, идентификаторы, команды CLI, флаги, пути к файлам
- Цитируемые сообщения об ошибках и строки логов
- Названия продуктов, названия эндпоинтов API, ключи конфигурации
- Числа с единицами измерения — каждое считается одним словом при подсчёте лимита
За пределами документации
Те же правила, другие цели применения. Полные адаптации — в references/use-cases.md:
- Сообщения об ошибках: сообщите, что произошло (простое прошедшее время), причину, если она известна, затем решение в повелительном наклонении. Никаких «Oops», никаких «Please ensure», никаких извинительных фраз-заполнителей.
- Runbook’и: родная территория STE. Шаги в повелительном наклонении, условия — в начале, предупреждения — перед шагом.
- Отчёты об инцидентах: только простое прошедшее время. «We have identified an issue that may have impacted» превращается в «Between 14:02 and 14:31 UTC, 12% of requests failed».
- Заметки о релизах: для breaking changes используется тот же шаблон, что для предупреждений, — сначала команда, затем риск.
- Инструкции для агентов (промпты, AGENTS.md): системный промпт — это процедура для читателя, который не может задать уточняющий вопрос. Одна инструкция на предложение, никакого «should», условие — в начале.
- Подготовка к переводу: изначальное назначение STE. Одно значение на слово плюс полная грамматика убирают большую часть неоднозначностей при переводе.
Самопроверка перед сдачей результата
Этот шаг обязателен. Прогоните черновик через эти четыре проверки:
- Посчитайте слова в трёх самых длинных предложениях. Превышение лимита 20/25 → разбейте предложение.
- Найдите в черновике:
'll,'re,'s(сокращённая форма),has been,have been,should, глаголы на-ingпосле запятой, точки с запятой. - Найдите каждое
ifиwhen. Каждое из них должно стоять в НАЧАЛЕ предложения, перед командой. «Increase the timeout if the network is slow» → «If the network is slow, increase the timeout». - Найдите глаголы, которые вы НЕ выбрали на шаге 3 раздела «Ваша задача» (набор check/verify/confirm). Замените каждое найденное вхождение на выбранный вами глагол.
Исправьте найденное и только затем сдавайте результат. Для полного аудита используйте references/checklist.md.
Полный пример
До (реальный неотредактированный вывод ИИ):
Connection timeouts. If sqlpipe hangs or fails with
dial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) — this is often a security group or firewall rule blocking the connection. If you’re connecting to a managed database (RDS, Cloud SQL, etc.), confirm the instance allows connections from sqlpipe’s IP. You can also try increasingsource.connect_timeout_secondsin your config, since a slow network path can trip the default timeout even when the connection eventually succeeds.
После (классифицировано как процедурный текст, глагол = «make sure», условия сначала, одна инструкция на предложение):
Connection timeouts. sqlpipe stops with
dial tcp: i/o timeoutwhen it cannot reach the Postgres port (5432 by default).
- Make sure that the host that runs sqlpipe can reach the Postgres port. A firewall or security group usually blocks it.
- If the database is managed (RDS, Cloud SQL), make sure that the instance accepts connections from the IP of sqlpipe.
- If the network is slow, increase
source.connect_timeout_secondsin the configuration.
Что изменилось: 40-словные предложения разбиты до менее 20 слов; «you’re» раскрыто в полную форму; «check/confirm» сведены к «make sure that»; каждое условие перенесено перед командой; «etc.» удалено; код и строки ошибок не тронуты.
Ограничения
STE предназначен для технических фактов и инструкций. Не применяйте его к рекламным текстам, блог-текстам или брендовым материалам — он по своей природе убирает убедительность. Если пользователь просит применить STE к маркетинговому тексту, скажите об этом прямо и предложите применить его к документации вместо этого.
Этот навык — неофициальный вспомогательный инструмент. Он не связан с ASD или STEMG и не одобрен ими, и ни один инструмент не может гарантировать полное соответствие STE. ASD-STE100 — зарегистрированный товарный знак ASD. Официальный стандарт можно бесплатно скачать на asd-ste100.org.
Справочные материалы
references/checklist.md— полная проверка с шаблонами для поиска, для режима проверки и финальных аудитовreferences/use-cases.md— развёрнутые адаптации: сообщения об ошибках, runbook’и, отчёты об инцидентах, коммиты, тексты интерфейса, i18n