Why we are engaged in translation of the book from English on the GitHub platform
Hello!
Recently, the rust_book_ru team completed the translation of the book “The Rust Programming Language” into Russian.
')
When I first joined the kgv translation project, we were told several times: “Are you making a transfer to GitHub? Strange you, there is another service for crowdsourcing translation - here is the link. ” We did not switch to other services and in the end this decision was fully justified.
I want to talk about why we still put the book on GitHub and why even a translator can be a bit of a programmer.
It is worth starting with the fact that assembling a book on Rust is not so simple. The original is written in a Rustbook format, and this is something like a Gitbook, but using rustdoc to directly generate pages. Those. the book is written as a set of Markdown files, and a set of html pages is generated from it - similar to static site generators like jekyll. But rustbook itself is not distributed when assembled, there is only the source code for Rust. And it is only going to the nightly version of the compiler, since uses some unstable features. So it turns out that for book rendering, we at least need to build a rustbook.
And since we wanted to automatically publish the new version, we needed the Continuos Integration service. We used Travis, and there is nothing special here - it works well and the setup is simple. With the introduction of container infrastructure, it is still accelerated.
There is probably one interesting point - as soon as rustbook created the html version of the book, the conversion to other formats (PDF, EBOOK, MOBI) can be launched in parallel. For this, we used GNU Parallel.
The conversion itself is done using Caliber, namely the ebook-convert utility. Unfortunately, it works in the end it is not as good as we would like. Caliber likes to apply his styles during 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, they would be very happy if you help us fix them.
In addition to the automatic publication of the new version, we also quite strictly reviewed most of the changes, both in the text and in the infrastructure. And if the infrastructure here is not so complicated, then everything was much more interesting with the contents of the book itself.
Rust introduces quite a lot of its terminology, and we spent a lot of time trying to at least come up with an acceptable translation of things like “ownership”, “borrowing”, and “crate”. The use of code review tools seemed to be useful: it is easier to follow 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 proposed using the new Reviewable service.
Although at first I was skeptical about using this tool, and there were some problems with it, the speed of its development is very good. In the end, I can recommend Reviewable as a replacement for gerrit, which is one of the best tools in this class. Reviewable is able to keep track of what changes are reviewed by the reviewer, which of the problems are solved, can run the editor directly from the web interface, understands the tags in the comments, allows you to compare different versions of the same patch, understands the build status on Travis and allows you to merge the branch into GitHub immediately your 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 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 a book, issues of taste, style, consistency with the original, the use of terminology, and other informal factors come out on top. Honestly, sometimes I was infuriated by comments from the suhr, and I think he was infuriated by my changes and answers. Fortunately, no serious confrontation has come.
At some point, I thought that the reviewer was doing no less important work than the translator himself. He checks the readability of the text as a reader directly, and ultimately, the result of our translation has become much better thanks to the review of changes.
Summing up, I would like to emphasize once again: we managed to build a good project infrastructure, which had a positive effect on the result, thanks to the fact that we used GitHub as a platform. Convenient review, automatic publication of a new version 5 minutes after the merge of a branch is cool. But Reviewable and Travis cannot be built into the crowdsourcing translation of ordinary texts, not to mention the fact that you cannot 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 translation of the 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.
Recently, the rust_book_ru team completed the translation of the book “The Rust Programming Language” into Russian.
')
When I first joined the kgv translation project, we were told several times: “Are you making a transfer to GitHub? Strange you, there is another service for crowdsourcing translation - here is the link. ” We did not switch to other services and in the end this decision was fully justified.
I want to talk about why we still put the book on GitHub and why even a translator can be a bit of a programmer.
It is worth starting with the fact that assembling a book on Rust is not so simple. The original is written in a Rustbook format, and this is something like a Gitbook, but using rustdoc to directly generate pages. Those. the book is written as a set of Markdown files, and a set of html pages is generated from it - similar to static site generators like jekyll. But rustbook itself is not distributed when assembled, there is only the source code for Rust. And it is only going to the nightly version of the compiler, since uses some unstable features. So it turns out that for book rendering, we at least need to build a rustbook.
And since we wanted to automatically publish the new version, we needed the Continuos Integration service. We used Travis, and there is nothing special here - it works well and the setup is simple. With the introduction of container infrastructure, it is still accelerated.
There is probably one interesting point - as soon as rustbook created the html version of the book, the conversion to other formats (PDF, EBOOK, MOBI) can be launched in parallel. For this, we used GNU Parallel.
The conversion itself is done using Caliber, namely the ebook-convert utility. Unfortunately, it works in the end it is not as good as we would like. Caliber likes to apply his styles during 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, they would be very happy if you help us fix them.
In addition to the automatic publication of the new version, we also quite strictly reviewed most of the changes, both in the text and in the infrastructure. And if the infrastructure here is not so complicated, then everything was much more interesting with the contents of the book itself.
Rust introduces quite a lot of its terminology, and we spent a lot of time trying to at least come up with an acceptable translation of things like “ownership”, “borrowing”, and “crate”. The use of code review tools seemed to be useful: it is easier to follow 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 proposed using the new Reviewable service.
Although at first I was skeptical about using this tool, and there were some problems with it, the speed of its development is very good. In the end, I can recommend Reviewable as a replacement for gerrit, which is one of the best tools in this class. Reviewable is able to keep track of what changes are reviewed by the reviewer, which of the problems are solved, can run the editor directly from the web interface, understands the tags in the comments, allows you to compare different versions of the same patch, understands the build status on Travis and allows you to merge the branch into GitHub immediately your 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 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 a book, issues of taste, style, consistency with the original, the use of terminology, and other informal factors come out on top. Honestly, sometimes I was infuriated by comments from the suhr, and I think he was infuriated by my changes and answers. Fortunately, no serious confrontation has come.
At some point, I thought that the reviewer was doing no less important work than the translator himself. He checks the readability of the text as a reader directly, and ultimately, the result of our translation has become much better thanks to the review of changes.
Summing up, I would like to emphasize once again: we managed to build a good project infrastructure, which had a positive effect on the result, thanks to the fact that we used GitHub as a platform. Convenient review, automatic publication of a new version 5 minutes after the merge of a branch is cool. But Reviewable and Travis cannot be built into the crowdsourcing translation of ordinary texts, not to mention the fact that you cannot 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 translation of the 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.
Source: https://habr.com/ru/post/266813/
All Articles