Привет, Хабр! Меня зовут Мария, я технический писатель в ИнфоТеКС. Представьте: вы запускаете новое приложение, тщательно проработанное, с инновационными возможностями и безупречным дизайном. Пользователь открывает описание функции и встречает ошибки. Например, «Выберите цепочку, содержаЩЕЕ правило».
Что происходит в этот момент? Небольшая опечатка, грамматическая ошибка или стилистическая неточность — и доверие к продукту подрывается, а значит, и к вашей компании. Проблема в том, что даже единичная небрежность в документации может свести на нет все усилия по созданию качественного продукта. Ведь небрежность в документации сразу бьёт по доверию: если текст не вычитан, то насколько надёжен сам продукт?
Чтобы такие ситуации не доходили до пользователей, в ИнфоТеКС выстроена система ревью, где ошибки выявляются и исправляются до публикации. Однако мы решили пойти дальше и посмотреть на ошибки системно — чтобы не просто править, а предотвращать их ещё на этапе создания черновика. Именно для этого провели «работу над ошибками» и проанализировали, какие недочёты возникают чаще всего.
Содержание
Анатомия ошибок: где прячутся неточности?
Мы провели аудит черновиков и выявили типичные причины ошибок, возникающих на этапе создания текстов. Это позволило нам точнее настраивать внутренние стандарты и обучающие материалы для авторов, чтобы повышать качество текстов до того, как они попадут на ревью.
Мы изучили 15 текстов: 12 документов, написанных нашими техническими писателями, и 3 статьи от разработчиков. Результаты были показательными: ошибки совершают все, но их характер различается.
В общей сложности мы обнаружили 669 ошибок. На каждый документ приходится 36 ошибок, а на статью — 78. Важно отметить, что средний объём анализируемых документов составляет 75 страниц, а статей — 7 страниц.
Типы ошибок распределились следующим образом:
Разница в составе ошибок объясняется стилистическими особенностями текстов:
Техническая документация в ИнфоТеКСе пишется согласно корпоративному стандарту и руководству по фирменному стилю. Это приводит к более однотипным ошибкам, часто связанным с соблюдением внутренних правил.
Технические статьи пишутся в более свободном стиле, что открывает простор для более разнообразных ошибок, особенно стилистических, лексических и логических.
Коммуникативная удача: почему грамотность важна?
Ошибки в документах и статьях могут иметь серьёзные последствия:
Потеря доверия. Пользователи перестают доверять документации, начинают искать информацию в других источниках, что увеличивает нагрузку на техподдержку.
Ущерб репутации. В худшем случае это сказывается на доверии к самому продукту и компании в целом. Неграмотный текст воспринимается как признак небрежности и низкого качества.
Неэффективная коммуникация. Ошибки могут привести к неправильному толкованию информации, что критично в ИТ-сфере, где точность имеет первостепенное значение.
Мы боремся за коммуникативную удачу — ситуацию, когда общение успешно, и все участники достигают поставленных целей. Рассмотрим пример:
Грамотность обеспечивает:
Быстрое и простое прочтение. Текст без ошибок легко воспринимается, не заставляя читателя спотыкаться и перечитывать фразы.
Удержание внимания. Читатель сосредоточен на смысле, а не на поиске и исправлении ошибок.
Эффективное бизнес-сотрудничество. Чёткие и однозначные тексты минимизируют недопонимания, ускоряют процессы и повышают продуктивность.
Когда мы пишем документ, нам важно, чтобы он был понятен и полезен пользователю. Когда пишем статью, мы привлекаем лояльную целевую аудиторию. В обоих случаях грамотность — главный инструмент.
Разделение ответственности: кто в ответе за качество?
Технический писатель, безусловно, несёт ответственность за качество текста. Однако создание документации — это командная работа.
Писатель не берёт информацию из головы: он опирается на спецификации, код и обсуждения с коллегами. Разработчики, аналитики и тестировщики — ценные носители информации о продукте. В ИнфоТеКСе они активно вовлекаются в процесс создания документации, привлекаются к ревью. Разбираясь в логике продукта, технический писатель может находить несостыковки — и это повод уточнить требования или реализацию. Обмен знаниями идёт в обе стороны, в результате чего продукт улучшается.
Разделение зон ответственности при работе над документом:
Технический писатель.
Основная задача — разработка документации. Для этого технический писатель собирает и систематизирует информацию о продукте, анализирует целевую аудиторию, оформляет документы в соответствии со стандартами компании и правилами русского языка, проверяет качество документации (инициирует проведение тестирования и ревью), вносит правки.
На уровне текста технический писатель отвечает за структуру и стиль документа, за грамматику, орфографию, пунктуацию, синтаксис, фактологию — в общем, за всё.Разработчик/Аналитик/Тестировщик.
Основная задача — предоставлять достоверную информацию о продукте. На этапе ревью члены продуктовой команды проверяют, чтобы в документации не было фактических ошибок. Вычитывают тексты с точки зрения технической корректности и полноты описаний, оценивают соответствие документации поведению продукта, проверяют сценарии использования.
В конечном итоге за качество документации — а значит, и за качество продукта — отвечает вся продуктовая команда. Это минимизирует количество ошибок в документах и самом продукте и сохраняет доверие пользователей.
План работы с ошибками: от реактивности к проактивности
Как же системно бороться с ошибками? Мы предлагаем действовать не только реактивно (выявлять ошибки на ревью), но и проактивно:
Обновлять «базу знаний». Регулярно актуализировать и пополнять источники информации о правилах русского языка и корпоративных стандартах.
Выявлять основные ошибки. Проводить анализ ошибок, чтобы понимать их характер и причины. И на основе этого корректировать «базу знаний» и план повторения правил.
Повторять правила. Систематически изучать и закреплять правила, связанные с наиболее частыми ошибками.
Разбираем ошибки: примеры и правила
Давайте рассмотрим наиболее частые грамматические и пунктуационные ошибки, с которыми мы сталкиваемся, и выясним, как их избежать.
Грамматические ошибки
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. Внутренние стандарты:
Руководство по стилю компании: документ, описывающий правила оформления, терминологию, тон общения и другие аспекты, специфичные для вашей организации. Его создание и регулярное обновление критически важны для единообразия и качества текстов.
Терминологический словарь проекта: глоссарий ключевых терминов, используемых в продукте и документации, с их определениями и правилами употребления.
