[Microbit-Python] Microbit Python Doc translation

Wed Nov 30 07:45:10 EST 2016

Hello,

so we plan to keep Readthedocs for https://microbit-
micropython.readthedocs.io/en/latest/.

I'm developing a workshop about Microbit for kids and use that for
microbitpolska.org.

My idea was to have like the software-carpentry lesson (for example
http://swcarpentry.github.io/python-novice-inflammation/) but the best
option would be to have a solution that also handles translations (sw
lessons are just in english).

Any idea ? Readthedocs ?

2016-11-28 12:59 GMT+01:00 Miklós András Danka <danka.miklos at gmail.com>:

> Makes a lot more sense! Let me ruminate and explore a bit more.
>
> -Miklos
>
> On Mon, Nov 28, 2016 at 10:51 PM Carlos Pereira Atencio <
> carlosperate at gmail.com> wrote:
>
>> Readthedocs already offers linked translations, so we can continue using
>> this platform. As far was what I would be looking for is better support for
>> translation tracking and updating, so that people could easily do small
>> contribution without a complex set up or trying to figure out what to
>> update by manually reading the English and translated documents to spot
>> unsynchronised bits. I mention some of my concerns with git here:
>> https://github.com/bbcmicrobit/micropython/pull/371#discussion_r89747053
>>
>>
>> I feel that ultimately, how live the documentation is in any language
>> will depend on how active the community is. That's irrespective of the
>> translation process. No?
>>
>>
>> I wouldn't quite agree with that, we (as the open source community)
>> always point to documentation, or in this case translations, as an easy
>> first step. If we make this difficult we might inadvertently be turning
>> away valuable contributions. I would expect some of this translations to
>> come also from not-so-technical communities, teachers for instance are
>> great candidates, and every time I even mention git/github to teachers I
>> never hear anything even remotely positive (this specific point is just my
>> personal experience and should be taken completely anecdotally). If we
>> ignoring the use of git for this solutions, then it would be a very manual
>> process to keep track of changes. Yes, "edit this on github" and PRs are
>> easy, and I think it does work great for normal documentation, but
>> translations are do not really follow the same model and I don't feel like
>> git really is the best way to manage them.
>>
>>
>>
>> On 28 November 2016 at 11:19, Miklós András Danka <danka.miklos at gmail.com
>> > wrote:
>>
>> That's true - all I expected from translations support is that they allow
>> listing translations together and possibly synchronising pages (so if I'm
>> on page X and click the other language, I'm taken to the right page).
>>
>> What else are you looking for? More fine-grained support? Support for
>> tracking/translating each English commit?
>>
>> I feel that ultimately, how live the documentation is in any language
>> will depend on how active the community is. That's irrespective of the
>> translation process. No?
>>
>> -Miklos
>>
>> On Mon, Nov 28, 2016 at 10:15 PM Carlos Pereira Atencio <
>> carlosperate at gmail.com> wrote:
>>
>> I am not really able to have a proper look until later, but from a very
>> quick skim gitbook doesn't seem to offer any translation feature to give it
>> an advantage over readthedocs. They both allow you to add translation to
>> their document generation, but there isn't any features to be able to
>> manage and synchronise such translations, no?
>>
>> Regards,
>> Carlos
>>
>> On 28 November 2016 at 11:02, Miklós András Danka <danka.miklos at gmail.com
>> > wrote:
>>
>> An alternative is Gitbook: https://www.gitbook.com/
>>
>>    - As far as I can see, it's free for public non-commercial uses
>>    - It supports translations: http://toolchain.gitbook.com/
>>    languages.html
>>    - It is non-technical to edit it - git backed, but no need to deal
>>    with git
>>    - For a live example, check out the documentation of Redux:
>>    http://redux.js.org/docs/basics/UsageWithReact.html
>>    <http://redux.js.org/docs/basics/UsageWithReact.html>
>>
>>
>> Do you expect a reasonably quick decision on this? If these discussions
>> take a longer time, then I think the best solution is if we fork the repo
>> and start the translation - leaving time to decide the exact process. If
>> you expect quick agreement, then we can wait until Gitbook or something
>> else is set up.
>>
>> Thoughts?
>>
>> -Miklos
>>
>>
>> PS. Nick, thanks for the response! I now requested membership.
>>
>>
>>
>>
>> On Sun, Nov 27, 2016 at 11:26 PM Carlos Pereira Atencio <
>> carlosperate at gmail.com> wrote:
>>
>> Let's not forget we still need to formalise the way we create and process
>> the translations: https://github.com/bbcmicrobit/micropython/pull/371
>> There's been some conversation there but not decisions done at all.
>>
>>
>>
>> On Sun, 27 Nov 2016, 12:13 Nicholas H.Tollervey, <ntoll at ntoll.org> wrote:
>>
>> Hi Miklós,
>>
>> Hmmm... I can't find your original email to this mailing list. Also, to
>> post you need to be a member (you can join here:
>> https://mail.python.org/mailman/listinfo/microbit) although I get
>> notified of all the non-member postings so let this one through! Also,
>> since you're not a member I'm not sure you'll see any replies to the
>> mailing list (hence me cc'ing you to my reply).
>>
>> Regarding translation and ReadTheDocs: it would be wonderful to have
>> Hungarian translations of the documentation! RtD have started to put
>> advertising on our documentation and there is also work on the pyedu.io
>> website for Python in education related resources.
>>
>> I wonder if we shouldn't just put our tutorials on there instead (along
>> with lots of other education related resources)..?
>>
>> Thoughts..?
>>
>> N.
>>
>>
>>
>> On 27/11/16 06:03, Miklós András Danka wrote:
>> > Hi,
>> >
>> > I haven't got any responses, so I wanted to ping again before I start
>> > hosting a fork.
>> >
>> > Read The Docs supports localisation in this way:
>> > http://read-the-docs.readthedocs.io/en/latest/localization.html
>> >
>> > Would you up for doing this?
>> >
>> > Thanks,
>> > Miklos
>> >
>> >
>> > On Mon, Oct 31, 2016 at 9:26 PM Miklós András Danka
>> > <danka.miklos at gmail.com <mailto:danka.miklos at gmail.com>> wrote:
>> >
>> >     Hello,
>> >
>> >     I'm Miklos Danka, a software engineer and a teacher (here's an
>> >     example
>> >     <http://blog.miklosdanka.com/tech-camp-beta-the-first-session>).
>> I'm
>> >     writing regarding the BBC Microbit Python edition - please let me
>> >     know if this is not the right place or contact for it.
>> >
>> >     First of all: *it's really awesome.* Incredible job, especially
>> >     around the documentation, which even less experienced kids
>> >     understood well. Very very cool.
>> >
>> >     Since I teach kids in Hungary, I wanted to translate the
>> >     documentation
>> >     <https://microbit-micropython.readthedocs.io/en/latest/> to
>> >     Hungarian. My question is: *do you have a recommended/preferred way
>> >     of publishing the translation?* I can always just fork the
>> >     repository - but that would miss out on the benefits of having the
>> >     documentations tracked together at the same website.
>> >     Would you recommend it as a Sphinx "version" (next to "latest" and
>> >     "stable")? Or does Sphinx provide and orthogonal translation
>> feature?
>> >
>> >     Any ideas/suggestions would be very welcome and appreciated.
>> >
>> >     Thanks!
>> >     Miklos
>> >
>> >
>> >
>> > _______________________________________________
>> > Microbit mailing list
>> > Microbit at python.org
>> > https://mail.python.org/mailman/listinfo/microbit
>> >
>>
>>
>> _______________________________________________
>> Microbit mailing list
>> Microbit at python.org
>> https://mail.python.org/mailman/listinfo/microbit
>>
>>
>>
>>
> _______________________________________________
> Microbit mailing list
> Microbit at python.org
> https://mail.python.org/mailman/listinfo/microbit
>
>

-- 
With Gravitational Cheers,

Christian
EuroPython Society board member
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/microbit/attachments/20161130/fa59e3c0/attachment-0001.html>