[swift-dev] Putting Swift Programming Language Book under Git version control

[Tim Bodeit]

I just saw Chris Lattners tweet about the translation section of the Swift Documentation page <https://swift.org/documentation/>.

The idea to encourage community driven translations into other languages is great.

But getting multiple people to collaborate on a single translation language requires some sort of collaboration platform.
For the Chinese translation this is GitHub. It’s only natural to follow this example for other languages. We’re developers after all and GitHub is where the rest of the Swift project is hosted.

I’d recommend pushing the English ebook to GitHub as well.

Think about future releases of Swift. As the language evolves, so will the book. 
The only way the maintainer of a translation can accommodate these changes, is if he knows what they are. 
For a German translation, I’d include a file with the latest commit hash (or submodule reference) of the english book repo that my translation is based on. 
Then when the English version is updated, all I need to do is to diff its current master against the commit hash. This will allow me to see if any of the changes are relevant to my translation.

When there is a git repo for the base language that can be forked as a starting point, this also encourages people to keep the original structure intact. Translations would also result in an epub file with the same style and format as the original. This would give them a more uniform look and allows for a central list that offers epub downloads for the various languages. People could also more easily jump between the english and their native language version of the book.

A benefit on the side: Why not accept community contributions on the English version of the book as well?

However, using git is not the only thing to take away from the Chinese translation project:
They converted everything to Markdown. Having a format that is easy to edit directly, and more importantly very easy to diff, is key to making community-based translations a success.
ePubs just being a zip file of html files are not a bad format, but something like Pandoc (http://pandoc.org/epub.html) would be better in my opinion.

What tool did Apple use internally to make the book? Do you have any other source files that you could provide?
Otherwise, just dumping the unzipped epub to GitHub would already help a lot.

Cheers,

Tim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-dev/attachments/20151217/39a27f7d/attachment.html>