[LRUG] Ruby Hacking Guide and a question

Mark Burns markthedeveloper at gmail.com
Thu Aug 15 01:18:26 PDT 2013


Hi LRUG,

Two points here:

* I'd like to introduce the Ruby Hacking Guide
* I'd like to ask a question about side-by-side documentation solutions

Ruby Hacking Guide
_________________

About a year ago, I decide to renew the efforts to translate a guide to the
internals of Ruby (1.7). I got as far as setting up a GitHub group and
project and co-ordinating the various efforts that had been made to
translate it from the original Japanese.
In the last month or so contributions, input, feedback and pull requests
have rocketed. It got to number 14 on the trending ruby projects on github
and number 3 on Hacker News.
I'm mostly pleased that we're nearly at a releasable full translation,
slightly mixed with embarrassment at how little I've done.
Anyway, it's not 100% translated/polished yet, but if you'd like to take a
look, then it's at http://ruby-hacking-guide.github.io/ or
https://github.com/ruby-hacking-guide/ruby-hacking-guide.github.com/ for
the source.

Question
-------------

In order to maintain accuracy of the original translation, particularly
when tweaking the phrasing of the English to sound more natural, it's
important to refer regularly back to the original. As such I'd like to have
a solution similar to the literate coffeescript style of documentation.
http://coffeescript.org/documentation/docs/grammar.html

I.e. 'comments' equate to the original Japanese, and 'source code' equates
to the English.
Then multiple views of the translation can occur. One aimed at translators,
one at English speakers, one at Japanese speakers.

Having a quick look through documentation solutions out there they are
mostly focused on specific programming languages. E.g. docco, rocco, etc.

I'd rather not roll my own if something is out there already. So, is anyone
aware of something that will allow me to use markdown/textile formatting
just to do the side-by-side comparison view?


Regards,

Mark
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lrug.org/pipermail/chat-lrug.org/attachments/20130815/f5d7d062/attachment-0003.html>


More information about the Chat mailing list