Правила письма: документация, статьи, тексты

1. Принципы

1. Точность и проверяемость

   Каждое утверждение — факт, который можно проверить. Нет данных — нет утверждения. Спекуляций и обещаний будущего избегать.

2. Объективность (нейтральность)

   Описывать, что объект есть и как работает. Оценку («лучше», «удобнее», «мощнее») выводит читатель из фактов, а не из прилагательных автора.

3. Ясность

   Короткие предложения, простые слова, термин определён при первом употреблении. Пишут для беглого просмотра, потом для чтения.

4. Краткость

   Без лишних слов и квалификаторов. Одна мысль — одно предложение.

5. Аудитория

   Сначала задача читателя, потом перечисление возможностей. Уровень знаний читателя — явный.

6. Единообразие

   Один термин на одно понятие во всём тексте. Не синонимизировать термины.

7. Структура

   Заголовки по смыслу, списки для перечислений, нумерация для последовательностей, таблицы для сопоставления параметров.

2. Чего избегать (с примерами)

2.1. Хвастовство и превосходство (puffery / peacock)

Субъективная похвала без проверяемого содержания.

Слова-маркеры: лучший, единственный, революционный, передовой, мощный, непревзойдённый, уникальный, не имеющий аналогов, фантастический, гениальный, world-class, cutting-edge.

• Плохо: «формат даёт свойства, которых нет ни у Word, ни у PDF».
• Плохо: «PDF фиксирует, но не редактируется; Word редактирует, но не фиксирует — мы делаем и то, и другое».
• Хорошо: привести факты в нейтральной форме (что формат делает) и, при необходимости, таблицу свойств без оценочных выводов. Вывод о преимуществе читатель сделает сам.

2.2. Принижение альтернатив

Сравнение через недостатки чужого продукта — это позиционирование, не документация.

• Плохо: «без главного недостатка PDF», «в отличие от громоздкого Word».
• Хорошо: «PDF фиксирует раскладку и не предполагает редактирования исходного содержимого» (факт об альтернативе, без оценки) — и отдельно факты о своём формате. Сравнение допустимо только как нейтральная таблица параметров с проверяемыми значениями.

2.3. Расплывчатые отсылки (weasel words)

Видимость авторитета без источника.

Маркеры: многие считают, как известно, эксперты говорят, исследования показывают, принято считать, общеизвестно.

• Плохо: «многие переходят на открытые форматы».
• Хорошо: убрать, либо дать конкретный источник/число.

2.4. Редакторские вставки

Навязывают читателю, что считать важным.

Маркеры: очевидно, конечно, разумеется, ясно, интересно, к сожалению, на самом деле, просто, стоит отметить, важно понимать.

• Плохо: «очевидно, это удобнее».
• Хорошо: убрать слово; факт говорит сам.

2.5. Преувеличение и категоричность (нет хеджирования)

Сильное утверждение требует сильного доказательства. Где знание неполное — смягчать.

• Сильные глаголы (доказывает, гарантирует, всегда, никогда) — только при доказательстве.
• Где результат вероятностный/эвристический — «как правило», «в типичном случае», «может», с указанием условий и ограничений.
• Плохо: «импорт PDF восстанавливает структуру документа».
• Хорошо: «импорт PDF восстанавливает структуру эвристически; точность зависит от исходного файла (для сканов — режим “страница как изображение”)».

2.6. Непроверяемые числа и обещания

• Плохо: «весит в разы меньше».
• Хорошо: «для типового договора (≈3 страницы, один шрифт) — ≈35–65 КБ» с пометкой, что это оценка, и от чего зависит. Незавершённое помечать как план, а не как факт.

3. Как писать (DOs)

• Описывать факты и механику: что делает, как устроено, при каких условиях, с какими ограничениями.
• Утверждение → по возможности рядом основание (число, ссылка, пример).
• Термины и аббревиатуры раскрывать при первом употреблении.
• Активный залог, настоящее время, прямое обращение в инструкциях («нажмите», а не «должно быть нажато»).
• Честно отделять готово от в работе/план. Незавершённое — отдельным разделом «Состояние».
• Ограничения и компромиссы называть прямо — это повышает доверие, а не снижает его.
• Нейтральная лексика передачи речи: сказал, описал, согласно (не признал, разоблачил, заявил).

4. Чеклист перед публикацией

• Нет слов из §2.1–2.4 (хвастовство, принижение, weasel, редакторские вставки).
• Каждое сравнение — проверяемый факт, а не оценка; принижения альтернатив нет.
• Сильные утверждения подкреплены; неполное знание — смягчено и с условиями.
• Числа/обещания проверяемы или помечены как оценка/план.
• Термины определены; один термин на понятие.
• Готовое отделено от планируемого.
• Текст читается как описание, а не как реклама.

Источники

• Google developer documentation style guide — developers.google.com/style (highlights, word list).
• Microsoft Writing Style Guide — learn.microsoft.com/style-guide (clarity, brevity, voice).
• Wikipedia Manual of Style / Words to watch — puffery, weasel words, editorializing, contentious labels, expressions of doubt.
• Нормы научного письма: объективный тон и хеджирование claims (избегать overstatement; «may/suggests/appears» вместо категоричного, с указанием ограничений).