Одна ошибка, и ты ошибся: как сохранить доверие к ИТ-продукту

Привет, Хабр! Меня зовут Мария, я технический писатель в ИнфоТеКС. Представьте: вы запускаете новое приложение, тщательно проработанное, с инновационными возможностями и безупречным дизайном. Пользователь открывает описание функции и встречает ошибки. Например, «Выберите цепочку, содержаЩЕЕ правило».

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

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

Содержание

• Анатомия ошибок: где прячутся неточности?

• Коммуникативная удача: почему грамотность важна?

• Разделение ответственности: кто в ответе за качество?

• План борьбы с ошибками: от реактивности к проактивности

• Разбираем ошибки: примеры и правила

• Полезные ресурсы для технического писателя

Анатомия ошибок: где прячутся неточности?

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

Мы изучили 15 текстов: 12 документов, написанных нашими техническими писателями, и 3 статьи от разработчиков. Результаты были показательными: ошибки совершают все, но их характер различается.

В общей сложности мы обнаружили 669 ошибок. На каждый документ приходится 36 ошибок, а на статью — 78. Важно отметить, что средний объём анализируемых документов составляет 75 страниц, а статей — 7 страниц.

Типы ошибок распределились следующим образом:

Разница в составе ошибок объясняется стилистическими особенностями текстов:

• Техническая документация в ИнфоТеКСе пишется согласно корпоративному стандарту и руководству по фирменному стилю. Это приводит к более однотипным ошибкам, часто связанным с соблюдением внутренних правил.

• Технические статьи пишутся в более свободном стиле, что открывает простор для более разнообразных ошибок, особенно стилистических, лексических и логических.

Коммуникативная удача: почему грамотность важна?

Ошибки в документах и статьях могут иметь серьёзные последствия:

• Потеря доверия. Пользователи перестают доверять документации, начинают искать информацию в других источниках, что увеличивает нагрузку на техподдержку.

• Ущерб репутации. В худшем случае это сказывается на доверии к самому продукту и компании в целом. Неграмотный текст воспринимается как признак небрежности и низкого качества.

• Неэффективная коммуникация. Ошибки могут привести к неправильному толкованию информации, что критично в ИТ-сфере, где точность имеет первостепенное значение.

Мы боремся за коммуникативную удачу — ситуацию, когда общение успешно, и все участники достигают поставленных целей. Рассмотрим пример:

Грамотность обеспечивает:

• Быстрое и простое прочтение. Текст без ошибок легко воспринимается, не заставляя читателя спотыкаться и перечитывать фразы.

• Удержание внимания. Читатель сосредоточен на смысле, а не на поиске и исправлении ошибок.

• Эффективное бизнес-сотрудничество. Чёткие и однозначные тексты минимизируют недопонимания, ускоряют процессы и повышают продуктивность.

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

Разделение ответственности: кто в ответе за качество?

Технический писатель, безусловно, несёт ответственность за качество текста. Однако создание документации — это командная работа.

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

Разделение зон ответственности при работе над документом:

1. Технический писатель.
   Основная задача — разработка документации. Для этого технический писатель собирает и систематизирует информацию о продукте, анализирует целевую аудиторию, оформляет документы в соответствии со стандартами компании и правилами русского языка, проверяет качество документации (инициирует проведение тестирования и ревью), вносит правки.

   На уровне текста технический писатель отвечает за структуру и стиль документа, за грамматику, орфографию, пунктуацию, синтаксис, фактологию — в общем, за всё.  

2. Разработчик/Аналитик/Тестировщик.
   Основная задача — предоставлять достоверную информацию о продукте. На этапе ревью члены продуктовой команды проверяют, чтобы в документации не было фактических ошибок. Вычитывают тексты с точки зрения технической корректности и полноты описаний, оценивают соответствие документации поведению продукта, проверяют сценарии использования.

   В конечном итоге за качество документации — а значит, и за качество продукта — отвечает вся продуктовая команда. Это минимизирует количество ошибок в документах и самом продукте и сохраняет доверие пользователей.

План работы с ошибками: от реактивности к проактивности

Как же системно бороться с ошибками? Мы предлагаем действовать не только реактивно (выявлять ошибки на ревью), но и проактивно:

1. Обновлять «базу знаний». Регулярно актуализировать и пополнять источники информации о правилах русского языка и корпоративных стандартах.

2. Выявлять основные ошибки. Проводить анализ ошибок, чтобы понимать их характер и причины. И на основе этого корректировать «базу знаний» и план повторения правил.

3. Повторять правила. Систематически изучать и закреплять правила, связанные с наиболее частыми ошибками.

Разбираем ошибки: примеры и правила

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

Грамматические ошибки

1. Н и НН в наречиях и кратких причастиях

Ошибка:

Времени гарантировано хватит для завершения технического обслуживания.

Как правильно:

Времени гарантированно хватит для завершения технического обслуживания.

Правило: Постановка Н или НН зависит от того, какой частью речи является слово. Краткое причастие пишется с одной Н, а наречие – с двумя (НН). Важно различать их:

• Краткое причастие отвечает на вопросы каков/какова/каково? Пример: Высокое качество вам гарантировано (каково?).

• Наречие можно заменить словами «точно, наверняка». Пример: Времени гарантированно (как?) хватит.

2. Выбор падежной формы после глагола

Ошибка:

Нельзя не обращать внимание на архитектурную безопасность на ранних этапах разработки.

Как правильно:

Нельзя не обращать внимания на архитектурную безопасность на ранних этапах разработки.

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

3. Написание сложных существительных, состоящих из двух частей, одна из которых на латинице

Ошибка:

Внутри размещаются Docker контейнеры с генераторами трафика, с системой мониторинга и прочими служебными сервисами.

Как правильно:

Внутри размещаются Docker-контейнеры с генераторами трафика, с системой мониторинга и прочими служебными сервисами.

Правило: По общему правилу, дефис объединяет части сложных слов, где одна или обе части выражены не словами, а цифрами, латинскими буквами или аббревиатурам. Примеры: 25-процентный, Т-образный, IBM-совместимый, ИТ-компания. Однако окончательное решение может быть закреплено в руководстве по стилю или терминологическом словаре вашей компании.

Пунктуационные ошибки

1. Обозначение числовых диапазонов

Ошибка:

Повторите шаги 26 — 31 для остальных учётных записей.

Как правильно:

Повторите шаги 26–31 для остальных учётных записей.

Правило: Если диапазон чисел написан в цифровой форме, то ставится тире без пробелов. Примеры: 3–4 недели, 12–13 дней, 6–7 страниц.

Если диапазон чисел описывается в словесной форме, то употребление дефиса и тире зависит от значения:

• Значение «от такого-то числа до такого-то числа» — ставится тире, отбивается пробелами. Пример: Длина должна быть три – четыре метра (т. е. от трёх до четырёх метров).

• Значение «то ли одно, то ли другое число» — ставится дефис, не отбивается пробелами. Пример: Кажется, этот текст занимает три-четыре страницы (то ли три страницы, то ли четыре).

2. Тире между подлежащим и сказуемым

Ошибка:

Если вы — администратор защищённой сети, то…

Как правильно:

Если вы администратор защищённой сети, то…

Правило: Тире ставится между подлежащим и сказуемым, если они оба выражены существительными в именительном падеже или глаголами в неопределённой форме. Однако тире не ставится, если:

• Сказуемое — существительное в именительном падеже, которое обозначает профессию или указывает на принадлежность человека к какому-либо движению.
  Пример: Наш пользователь разработчик.

• Подлежащее — личное местоимение, сказуемое — существительное в именительном падеже.
  Пример: Вы руководитель ИТ-отрасли.

• Перед сказуемым, выраженным существительным в именительном падеже, стоит вводное слово или наречие.
  Пример: Главное в ответе менеджера, безусловно, чёткая аргументация и опора на факты.

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

3. Запятая при союзе КАК

Ошибка:

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

Как правильно:

В основании классической пирамиды тестирования будут находиться unit-тесты как самый стабильный и многочисленный класс автотестов.

Правило: Запятая перед как ставится, если оборот имеет значение сравнения или уподобления. Запятая перед как не требуется, если как можно заменить на в качестве. В нашем примере unit-тесты выступают в качестве самого стабильного класса, поэтому запятая не нужна.

Ключевые выводы

Качество текста в ИТ-продуктах — это неотъемлемая часть пользовательского опыта и репутации компании. Системный подход к борьбе с ошибками, включающий регулярное обучение, анализ и применение стандартов, позволяет значительно улучшить качество текстов и, как следствие, повысить доверие к продукту.

Борьба за грамотность — это показатель уважения к пользователю, залог эффективной коммуникации внутри команды и признак сильного бренда на рынке. В мире, где документация и технический контент стали частью продукта, сила — в знании языка, на котором пишешь. Инвестиции в грамотность — это инвестиции в качество, доверие и успех вашего ИТ-продукта.

А как у вас в команде следят за качеством текстов? Делитесь опытом в комментариях!

Полезные ресурсы для технического писателя

Для обновления и поддержания актуальной «базы знаний» рекомендуем следующие источники:

1. Общие правила русского языка:

• Справочный портал «Грамота.ру»

• «Нормы современного русского языка. Учебно-методическое пособие», Бортников В. И., Пикулева Ю. Б.

• «Справочник по правописанию и литературной правке» Э. Розенталь

• «Грамматический словарь русского языка: Словоизменение», Зализняк А. А.

• «Трудные случаи русской пунктуации. Словарь-справочник», Пахомов В. М., Свинцов В. В., Филатова И. В.

2. Общие руководства по стилю:

• «Справочник издателя и автора», А. Мильчин, Л. Чельцова

• «Стилистика русского языка» И. Голуб

• «Пиши, сокращай» и «Ясно, понятно», Максим Ильяхов

3. Внутренние стандарты:

• Руководство по стилю компании: документ, описывающий правила оформления, терминологию, тон общения и другие аспекты, специфичные для вашей организации. Его создание и регулярное обновление критически важны для единообразия и качества текстов.

• Терминологический словарь проекта: глоссарий ключевых терминов, используемых в продукте и документации, с их определениями и правилами употребления.