Мы пишем документацию tarantool.io на английском, а потом переводим на русский. Раньше переводили сами, а теперь отдали эту работу внештатной переводчице Кате. В целом это прекрасно и мы очень довольны. Доки наконец-то переводятся, а техписатели освободились для основной работы (привет, теория ограничений).
Чтобы помочь Кате войти в тему и поддержать хорошее качество, мы проверяем перевод. Иногда находим ошибки. Из этих ошибок я очень много узнал о том, где наши доки непонятны и как их можно улучшить.
Ошибки в переводе часто встречаются там, где исходный текст написан сложно. Там могут быть сложносочинённые предложения, уточнения в скобках, путаница в местоимениях, непонятные причинно-следственные связи. Это сложно читать и понимать вообще всем, включая переводчиков.
Другой типичный случай — когда код не размечен как
код. Вот мы пишем про integer. Это абстрактное «целое число» или «переменная типа integer»? Разница существенная, мы всё-таки пишем про СУБД. Если это тип данных, то мы должны выделить его моноширинным шрифтом. Например: the Lua integer type can hold integer values from _____ to _____.Вывод такой: переводчики ошибаются там, где ошибутся и многие другие читатели. Поэтому мы (писатели) берём на себя ответственность за все систематические ошибки в переводе. Изучаем их, ищем причину, вырабатываем правило, внедряем его. Конечно, исправляем ошибки в оригинальном тексте и помогаем переводчикам исправлять перевод.
А что значит «внедрить правило»? Задокументировать, применять в ревью новых текстов, исправлять в старых, добавить в автотесты.