Всем привет!

Недавно команда rust_book_ru закончила перевод книги «The Rust Programming Language» на русский язык.



Когда я только присоединился к проекту перевода, начатого kgv, нам несколько раз говорили: «Вы делаете перевод на GitHub? Странные вы, для краудсорсинг-перевода есть другой сервис — вот ссылка». Мы не стали переходить на другие сервисы и в итоге это решение полностью оправдалось.

Я хочу рассказать о том, почему мы всё же разместили книгу на GitHub и почему даже переводчику полезно быть немного программистом.

Стоит начать с того, что сборка книги по Rust не так уж и проста. Оригинал написан в формате Rustbook, а это нечто вроде Gitbook, но использующее rustdoc для непосредственно генерации страниц. Т.е. пишется книга в виде набора Markdown-файлов, и из неё генерирутся набор html-страниц — похоже на статические генераторы сайтов вроде jekyll. Но сам rustbook не распространяется в собранном виде, есть только исходный код на Rust. И он собирается только nightly-версией компилятора, т.к. использует некоторые нестабильные возможности. Вот и получается, что для рендеринга книги нам по крайней мере уже нужно собрать rustbook.

А поскольку мы хотели и автоматической публикации новой версии, нам нужен был сервис Continuos Integration. Мы использовали Travis, и тут ничего особенного — работает он хорошо и настройка несложная. С введением контейнерной инфраструктуры всё ещё и ускорилось.

Тут есть, наверное, один интересный момент — как только rustbook создал html-версию книги, преобразование в остальные форматы (PDF, EBOOK, MOBI) можно запускать параллельно. Для этого мы использовали GNU Parallel.

Само преобразование делается с помощью Calibre, а именно утилитой ebook-convert. К сожалению, работает в итоге она не так хорошо, как хотелось бы. Calibre любит применять свои стили в процессе преобразования, и они почему-то конфликтуют с стилями rustbook.

В итоге у нас пара проблем с EBOOK и MOBI. Если кто-то разбирается в том, как работает Calibre и/или в CSS — были бы очень рады, если вы поможете нам их починить.

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

Rust вводит довольно много своей терминологии, и много времени мы потратили на то, чтобы хотя бы придумать приемлемый перевод вещей вроде «ownership», «borrowing», и «crate». Использование инструментов code review виделось полезным: так проще следить за использованием терминов, за общим стилем, и вообще помогать новичкам в переводе.

В итоге с этим аспектом нам помог переводчик другой книги по Rust, Rust by Example: suhr. Его идеей было внедрить code review: он предложил использовать новый сервис Reviewable.

Хотя поначалу я был настроен скептически относительно использования этого инструмента, и с ним возникали некоторые проблемы, скорость его развития очень радует. В итоге я могу рекомендовать Reviewable в качестве замены gerrit, который является одним из лучших инструментов этого класса. Reviewable умеет следить за тем, какие изменения просмотрены рецензентом, какие из проблем решены, умеет запускать редактор прямо из веб-интерфейса, понимает метки в комментариях, позволяет сравнивать разные версии одного патча, понимает статус сборки на Travis и позволяет слить ветку на GitHub сразу из своего интерфейса. Как и Travis, он полностью бесплатен для Open Source-проектов на GitHub. Для примера, вот страница Reviewable с рецензией изменений в главе о FFI.

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

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

Подводя итог, хотелось бы ещё раз подчеркнуть: нам удалось построить хорошую инфраструктуру проекта, которая положительно повлияла на результат, благодаря тому, что мы использовали в качестве площадки GitHub. Удобное рецензирование, автоматическая публикация новой версии через 5 минут после слияния ветки — это классно. Но Reviewable и Travis не встроишь в сервис краудсорсинг-перевода обычных текстов, не говоря о том, что там не сделаешь автоматического развёртывания с учётом всех особенностей публикации.

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