Отчёты пишутся простым инженерным языком, без проектного жаргона

Владелец просил дважды и резко: «вот я вроде тимлид с большим опытом, но половину твоего текста не понимаю» и «как заебал же ты со всякими словами типа печатник и прочее, пиши понятно для программистов».

Слова, на которых он спотыкался, и чем их заменять:

Почему это правило, а не вкус. Жаргон, который агенты выработали внутри проекта, для читателя — шум, и он перестаёт видеть суть отчёта. Термин можно вводить только вместе с объяснением при первом употреблении.

Как применять. В переписке с агентами жаргон допустим — они в нём работают. Их отчёты переводить, а не пересылать как есть.

Поправка 18–20 августа 2026: правило было про отчёты, а утекло на сайт

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

Замер. В прозе docs/site/*.md — вне блоков кода, вне встроенного кода и вне подстановок — 745 вхождений одиннадцати внутренних слов. Самые частые: «эталон» 190, «близнец» 130, «сторож» 124, «корпус» 113. (Счёт 729 по grep исходников был больше и вёл не туда: он включал имена ключей подстановки вида {{корпус.функций}}, которых читатель не видит вовсе.)

Чего не хватало правилу. Оно называло слова, но не называло АДРЕСАТА, и поэтому не работало ни в одну сторону: на страницах жаргон стоял, а во внутренних заметках его начинали вычищать зря. Правило теперь двустороннее:

• внутри проекта жаргон полезен — он короче и точнее. docs/zettel/, комментарии в коде, задания агентам, переписка: трогать не надо;
• снаружи запрещён — страницы сайта, README, man flang, курс и сообщения самого компилятора: справка, диагностика, тексты отказов. Человек, поставивший язык, читает их первыми.

Замены:

Плюс английские пары (witness, twin, corpus, ledger, byte-for-byte, fixed point): английские страницы болеют тем же.

Список слов не спасает — он кончается. Правило важнее: если слово требует, чтобы читатель знал нашу внутреннюю кухню, — на публичной странице ему не место. Либо объясни одной фразой при первом употреблении, либо убери.

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

Где на самом деле лежит жаргон. 610 из 745 вхождений — на одной странице, печатном журнале вливаний (docs/site/changelog.md), и там их не вычистить: это заголовки слияний из истории репозитория. Правильный ход для неё — не правка текста, а место в меню: журнал адресован тому, кто развивает язык. Написанные руками страницы вычищены со 135 вхождений до 1, и оставшееся — цитата ответа компилятора, объяснённая тут же следующей фразой.

Слово течёт и из самого инструмента. flang emit печатает читателю «таблицу объявленных типов строит слой типов свидетеля» — это не текст страницы, это строка в bootstrap/. Пока её не переписали, слово будет возвращаться на страницы вместе с прогонами.

Чем держится. docs/jargon.json (слова и список поверхностей, правится без правки прогона) и scripts/jargon-guard.mjs. Долг числом на файл: вырасти не имеет права, а упадёт — прогон попросит вписать новое число, чтобы потолок полз только вниз. Слово, стоящее законно, снимается исключением с ЦИТАТОЙ объяснения или имени вещи; выдумать цитату нельзя, прогон сверяет её с файлом.

Связано: owner-decisions, most-site-jargon-comes-from-one-printed-page, a-page-that-reports-our-work-is-not-a-guide