Принципы документирования и локализации, или как получить хорошую локализацию минимальными затратами

    Всем привет!

    Меня зовут Денисов Александр. Я работаю в компании Naumen и отвечаю за документирование и локализацию программного продукта Naumen Contact Center (NCC).

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

    image

    Введение


    Часто компания задумывается о локализации ПО тогда, когда продукт уже готов и для него написана документация. И так же часто бывает уже поздно что-либо сделать, чтобы в короткие сроки получить хорошую локализацию и не потратить на это огромное количество ресурсов.

    Подробно написать обо всех проблемах и трудностях в одной статье невозможно, поэтому я расскажу немного об основных этапах документирования и локализации и затрону несколько, на мой взгляд, наиболее важных вопросов:

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

    Исходя из своего многолетнего опыта работы над документированием и локализацией NCC попробую ответить на эти вопросы.

    Особенности NCC и процесса разработки


    Naumen Contact Center — это сложное программное обеспечение для организации крупных корпоративных или аутсорсинговых контактных центров.

    В чем сложность документирования и локализации этой системы:

    1. Система не облачная.
    2. Сложная настройка, много интеграций с различными системами.
    3. Поддержка нескольких версий.
    4. Как следствие п. 1-3 мы имеем сложные внедрения и обновления. У каждого клиента своя версия, своя конфигурация и интеграции с различными системами.
    5. Система не массовая, ее использует только крупный бизнес. Поэтому число клиентов не очень большое по сравнению с небольшими массовыми продуктами.
    6. Большое число специфических терминов.
    7. Многоролевая модель. А это значит, что документация и интерфейс должны подстраиваться под особенности каждой роли (уровень знаний и особенности задач).
    8. Интерфейсы системы содержат около 30 000 строк текста и написано около 3000 страниц сложной технической документации.
    9. Релизы выходят 2-3 раза в год.
    10. После каждого релиза обновляется и дополняется примерно 10% текста интерфейса и документации.
    11. 3 языка: русский (исходный), английский и немецкий.

    Жизненный цикл разработки


    Давайте посмотрим на жизненный цикл разработки ПО и выделим только те этапы, которые касаются документирования и локализации:

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

    image

    А теперь давайте представим, что в интерфейсе была допущена одна незначительная ошибка. Она автоматом распространяется на каждый этап, на несколько версий и языков.

    image

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

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

    Организация текста в интерфейсе


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

    image

    На изображении приведена простая кнопка, она открывает какую-то форму с параметрами, где эти параметры можно изменить. Таких кнопок в системе десятки. На русском языке для такой кнопки обнаружилось 3 варианта, локализация на английский содержала уже 7 вариантов.

    В этой ситуации сразу возникает большое желание навести порядок в строках интерфейса. Для этого предлагаю применять следующие правила:

    • Деление всех строк на группы.

      Все строки следует делить на группы в соответствии с типом элементов интерфейса. Даже если строки имеют один и тот же текст, для разных групп могут применяться разные правила перевода. Например, правило капитализации первой буквы каждого слова в английском языке. Для одних типов элементов интерфейса оно применяется, для других нет.
    • Удаление дублей.

      В каждой группе имеет смысл удалить все дублирующиеся строки, то есть строки с одинаковым текстом. Тогда останется единственный вариант как на русском языке, так и на других языках. Это экономит затраты на перевод. Отмечу, что скорее всего повторяющиеся строки все же останутся, так как в некоторых случаях контекст у них может быть разный. Более того, такие строки, с одинаковым исходным текстом могут переводиться по-разному. Например, слово Имя, в контексте имени человека может переводиться как First name, а в контексте имени файла просто Name.
    • Добавление контекста в идентификаторы строк.

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

    image

    К сожалению, применить подобные правила ко всем существующим 30 000 строкам сразу, очень трудоемко. Здесь мы находимся на начальном этапе и постепенно приводим в порядок наиболее часто повторяющиеся строки и разрабатываем правила для новых строк. Но согласитесь, было бы супер, если бы все правила были прописаны и выполнялись сразу!

    Процесс документирования и локализации


    Давайте взглянем на процесс документирования и локализации с привязкой ко времени. Если начать документирование и локализацию раньше, чем закончилась разработка фичи, то придется все переделать (возможно, несколько раз).

    То же самое с переводом документации.

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

    image

    Если же процессы не согласованы, и мы вовремя не отслеживаем все изменения, то «ничего-ничему-нигде» не будет соответствовать.

    Документация не будет соответствовать интерфейсу. Скриншоты не будут соответствовать интерфейсу и тексту документации.

    image

    То же самое с локализацией. Текст интерфейса и документации на исходном языке не будет соответствовать тексту интерфейса и документации на других языках.

    image

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

    image

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

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

    Проблемы терминологии


    На этапе документирования и локализации мы постоянно сталкивались с проблемами терминологии:

    • Одни и те же сущности назывались по-разному, а разные сущности назвались одинаково.
    • Одни и те же термины переводились по-разному, а разные термины переводились одинаково.
    • Какая-либо сущность могла приравниваться к ее дочерним сущностям, из которых она состоит, или родительским сущностям.
    • Выбирались неудачные или неверные термины для обозначения сущности.

    Процесс же разработки у нас какое-то время выглядел так:

    • Аналитики пишут постановку.
    • Постановку тестируют тестировщики.
    • Разработчики кодируют.
    • Тестировщики тестируют результат.

    image
    А при попытках вклиниться в этот процесс с терминологией, мы получали такие отговорки:

    • Вы затормозите весь процесс.
    • Это вообще все не так важно.
    • У вас есть инструменты, вы все можете поправить потом.

    Но «потом» выяснялось, что поправить мы можем далеко не все. Например, были ситуации, когда из-за неверно понятой терминологии объекты системы размещались не на тех уровнях иерархии или объединялись в неверные группы.

    Сейчас мы проверяем термины и текст интерфейса параллельно тестированию постановки. То есть пока тестировщики пишут свои замечания, мы пишем свои.

    image

    Что мы делаем во время тестирования постановки:

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

    При выявлении новых терминов мы добавляем их в глоссарий, при этом:

    • Добавляем определение или контекст.
    • Указываем на взаимосвязь с другими терминами (указываем родительские и дочерние термины).
    • Пытаемся сразу указать английское значение, так как после выбора английского названия иногда становится понятно, что русское выбрано не очень верно.

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

    Документирование


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

    • Использование системы с единым источником.
    • Использование глоссария.
    • Использование руководства по стилю.
    • Деление документации на небольшие и легко отчуждаемые документы.
      Это стоит делать, даже если основной формат – это Web. Если понадобится, можно переводить не всю документацию, а только самые важные документы, или делать это поэтапно.

    Теперь расскажу про некоторые, особо важные моменты процесса документирования.

    Переиспользование текста


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

    image

    Какие это дает преимущества:

    • Исключаются ошибки в текстах элементов интерфейса, если они упоминаются в документации. Тексты элементов интерфейса в документации всегда идентичны текстам в интерфейсе.
    • Если строки текста поменялись в интерфейсе, они автоматически меняются в документации.
    • Исключаются ошибки при переводе текстов элементов интерфейса в документации.
    • Переводчик тратит меньше времени на работу.

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

    image

    Как вы можете заметить, текст кнопки Сохранить в сниппет также подставляется из переменной.

    Это дает следующие преимущества:

    • Одинаковые по смыслу предложения везде идентичны, а значит повышается единообразие текста.
    • Сокращаются затраты на разработку документации за счет переиспользования.
    • Переводятся такие предложения только 1 раз. Это сокращает затраты переводчика.

    Скриншоты и другие изображения


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

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

    С использованием скриншотов бывают и другие трудности. Например, как отследить все изменения, если в интерфейсе меняется одна строка текста, которая используется в 50 местах?

    Как потом найти все скриншоты этих 50 мест, чтобы заменить их в документации?

    Для решения этой проблемы мы используем инструмент QVisual, который разработали в компании Tinkoff. Процесс работы с ним выглядит так:

    1. Во время разработки документации под каждым скриншотом мы делаем ссылку на стенд, где этот скриншот сделан.
    2. В определенный момент готовим список всех ссылок.
    3. Загружаем полученный список в QVisual.
    4. QVisual пробегает по одной версии продукта и делает набор скриншотов.
    5. Далее берем новую версию продукта и QVisual пробегает по ней, используя те же ссылки.
    6. Затем QVisual сравнивает 2 набора скриншотов и генерирует отчет. В отчете, в графическом виде можно увидеть различия между двумя версиями. Пример ниже. Сразу видно, что в новой версии скриншота появилось дополнительное поле Язык пользовательского интерфейса.
    7. Далее повторяем процедуру сравнения (п. 1-6) для каждого языка.
    8. Берем отчеты, и проходимся по скриншотам в документации.

    image

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

    Правда, не все окна можно открыть при помощи ссылок и это работает только для Web-интерфейса, но часть проблем с обновлением скриншотов это все равно снимает.

    Локализация интерфейса


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

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

    • Используем глоссарий.
    • Используем память переводов.
    • Используем руководство по стилю.
    • Используем контекст.
    • Используем автоматическую проверку качества (Quality Assurance или QA).

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

    Может быть несколько способов предоставления контекста:

    • Как я уже писал выше, контекст может быть заложен в самом идентификаторе строки или в дополнительных полях файлов ресурсов (если позволяет формат).
    • Могут быть добавлены скриншоты. На данный момент мы имеем возможность к особо сложным строкам вручную добавлять скриншоты.
    • Предоставление стендов и документации на исходном языке. Как показывает практика, этот способ не работает. Переводчики обычно не пользуются предоставленными им материалами и стендами. Возможно потому, что время на перевод одной строки увеличивается многократно.

    Перевод документации


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

    • Сначала выполняем перевод текстов для скриншотов и других изображений. Как я писал выше, скриншоты делаются параллельно с переводом документации. Делается это на стенде с использованием переведенных текстов для скриншотов.
    • Переводим только изменившиеся и новые строки. Переведенные ранее строки со 100% совпадением просто не смотрим. Да, можно каждый релиз заново вычитывать всю документацию, но с учетом того, что каждый релиз обновляется примерно 10% текста, вычитывать оставшиеся 90% текста – это неоправданные затраты.
    • Используем глоссарий. Глоссарий должен быть переведен ранее, на этапе локализации интерфейса.
    • Используем память переводов документации.
    • Используем память переводов интерфейса.
    • Используем руководство по стилю.
    • Используем автоматическую проверку качества (QA).

    Организационная структура и обратная связь


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

    image

    Обратная связь от одного отдела к предыдущему в таком варианте будет затруднена, взаимодействие между сотрудниками разных отделов налаживается сложно. Решение всех вопросов через руководителя тоже «узкое горлышко». У каждого руководителя свое видение, цели и приоритеты. Много времени может тратиться на дополнительные согласования.

    На мой взгляд за все тексты на всех языках должен отвечать один отдел.

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

    Приведу пример.

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

    Оказалось, что переводчик видит одинаковые по смыслу, но по разному написанные предложения и делает для них один и тот же перевод. Мы инициировали задачу и технический писатель заменил все разные варианты одного и того же по смыслу текста на один сниппет. Теперь таких повторяющихся ошибок больше не будет. Специалистам не придется тратить время на их анализ, а перевод на новые языки в будущем будет проще.

    image

    В общем случае, если у переводчика во время перевода возникают вопросы, то для нас это уже «звоночек» о том, что что-то не так на ранних этапах и надо делать задачу на исправление.

    Какое качество документации нужно


    Перед тем как пытаться сделать идеальную документацию на всех языках, стоит задуматься, а какое качество нужно? Ответить на этот вопрос помогут дополнительные вопросы:

    • Кто пользователи документации?
      Если документация во внешнем доступе и клиенты на основе нее принимают решение о покупке продукта, то качество должно быть близко к идеальному. Если документацией чаще всего начинают пользоваться уже после внедрения системы и читают ее преимущественно инженеры (у нас именно так), качество документации уже не повлияет на решение о покупке. Главное, чтобы инструкции помогали решать задачи. В этой связи важно, чтобы все было правильно именно в технической части: форматы команд, функции, примеры и так далее. На грамматические или стилистические ошибки инженеры вряд ли обратят особое внимание.
    • Каково число пользователей?
      Если документацию никто не читает, то и об ошибках никто не скажет, никто их не увидит. Все вычитки будут зря. На сколько уместно в этом случае вкладываться в качество документации или вычитывать переводы? Возможно, лучше сначала потратить часть ресурсов на то, чтобы привлечь пользователей.

    Вычитка документации и обратная связь пользователей


    Если принято решение вычитывать документацию:

    • Вычитывать можно далеко не все.

      Постройте статистику по использованию документации и отдайте на вычитку, например, топ-50 страниц, которые читают сотни и тысячи пользователей. Если какие-то страницы читают 1-2 раза в год, то ими можно пренебречь.
    • Лучше вычитывать готовую документацию.

      Не все проблемы можно увидеть в CAT-системе. Например, соответствие картинок тексту или состыковка разных частей текста в общем документе (сниппеты, переменные), единый подход к переводу заголовков и тому подобное.
    • Никто кроме пользователей, которые реально решают задачи с помощью документации, не скажет, качественная у вас документация или нет.
    • Никто кроме носителя языка не скажет, на сколько качественно переведена документация.

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

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

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

    Что заставляет пользователей отправлять обратную связь:

    • Все любят критиковать.

      И чтобы критика не оставалась где-то в курилке, можно сделать простой способ попадания ее к нам. Мы сделали очень простую форму. Можно выделить текст с ошибкой, нажать Ctrl+Enter и нажать кнопку Отправить. Иногда комментарии писать даже не обязательно. Это занимает очень мало времени и не вызывает особых трудностей.
    • Замечания должны обрабатываться.

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

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

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

    Выводы


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

    Сначала разберитесь, что именно необходимо на текущий момент и сделайте только это, а затраты увеличивайте по мере возрастания потребностей.

    Это была достаточно общая статья о процессах документирования и локализации в целом. В будущем попробую написать о более узких темах.

    Спасибо, если дочитали до конца! Желаю вам успехов в работе и отладке своих процессов документирования и локализации!

    Буду рад ответить на вопросы, обсудить ваши мысли и идеи!
    NAUMEN
    70.15
    Решаем истинные задачи
    Share post

    Comments 2

      0
      Было упоминание, что вы используете систему работы с единым источником, но названия не упомянули. Интересно знать чем пользуются)
        0
        Мы используем MadCap Flare. Возможно стоило указать названия инструментов, но хотелось написать общую статью безотносительно к инструментам. Думаю, тот же вопрос преобразования файлов ресурсов в переменные и использование переменных в Flare заслуживает отдельной статьи, надо подумать над этим. :)

      Only users with full accounts can post comments. Log in, please.