Why do we translate books from English on the GitHub site

Hello!

Recently, rust_book_ru team completed the translation of The Rust Programming Language into Russian.



When I just joined the translation project started by kgv , they told us several times: “Are you translating on GitHub? Strange you, there is another service for crowdsourcing translation - here is the link. ” We did not switch to other services, and as a result, this decision was fully justified.

I want to talk about why we still posted the book on GitHub and why even a translator is helpful to be a little programmer.

It’s worth starting with the fact that building a Rust book is not so simple. The original is written in Rustbook format, and this is something like Gitbook, but using rustdocfor directly generating pages. Those. a book is written in the form of a set of Markdown files, and a set of html pages is generated from it - it looks like static site generators like jekyll. But rustbook itself is not distributed in assembled form, there is only source code for Rust. And it is collected only by the nightly version of the compiler, because uses some unstable features. So it turns out that to render the book we at least need to build a rustbook.

And since we wanted automatic publication of the new version, we needed the Continuos Integration service. We used Travis, and there is nothing special - it works well and the setup is simple. With the introduction of container infrastructure, it still accelerated.

There is probably one interesting point here - as soon as rustbook has created an html version of the book, conversion to other formats (PDF, EBOOK, MOBI) can be started in parallel. For this we used GNU Parallel.

The conversion itself is done using Caliber, namely the ebook-convert utility. Unfortunately, in the end it does not work as well as we would like. Caliber loves to apply its styles in the conversion process, and for some reason they conflict with rustbook styles.

As a result, we have a couple of problems with EBOOK and MOBI. If someone understands how Caliber and / or CSS works, you would be very happy if you could help us fix them.

In addition to the automatic publication of the new version, we also fairly strictly reviewed most of the changes, both in the text and in the infrastructure. And if the infrastructure here is not so complicated, then with the very contents of the book everything was much more interesting.

Rust introduces quite a bit of its terminology, and we spent a lot of time at least coming up with an acceptable translation of things like “ownership”, “borrowing”, and “crate”. Using code review tools seemed useful: it’s easier to keep track of the use of terms, the overall style, and generally help newcomers to translate.

As a result, the translator of another book on Rust, Rust by Example : suhr, helped us with this aspect . His idea was to implement code review: he suggested using a new serviceReviewable .

Although at first I was skeptical about using this tool, and there were some problems with it, the speed of its development is very pleasing. In the end, I can recommend Reviewable as a replacement for gerrit, which is one of the best tools in this class. Reviewable can monitor what changes the reviewer has watched, which of the problems have been resolved, can launch the editor directly from the web interface, understands tags in comments, allows you to compare different versions of one patch, understands the build status on Travis and allows you to merge the branch on GitHub right from its interface. Like Travis, it is completely free for Open Source projects on GitHub. For an example, here is the Reviewable page with a review of the changes in the FFI chapter.

suhr did a lot of reviewing changes in the text of the book, in particular mine. And sometimes this process went very slowly and hard. Even the code is difficult to review, and in the case of the book, questions of taste, style, consistency with the original, the use of terminology, and other informal factors come first. Honestly, sometimes I was infuriated by suhr’s comments, and I think he was enraged by my changes and answers. Fortunately, no serious confrontation came to pass.

At some point, I thought that the reviewer is doing no less important work than the translator himself. He checks the readability of the text as a direct reader, and in the end, the result of our translation has become much better thanks to the review of changes.

To summarize, I would like to emphasize once again: we managed to build a good project infrastructure, which positively affected the result, thanks to the fact that we used GitHub as a platform. Convenient reviewing, automatic publication of a new version 5 minutes after the merge of a branch is cool. But Reviewable and Travis cannot be integrated into the crowdsourcing translation service of ordinary texts, not to mention that you will not do automatic deployment there taking into account all the features of the publication.

And it turns out that even in such non-programmer work as translating a book, there were several tasks for programmers. DevOps will help even a technical writer. Organizing a good infrastructure and process will help, even if the project does not seem to require the attention of programmers at all.

Also popular now: