[Microbit-Python] Microbit Python Doc translation

[Radomir Dopieralski]

I looked at gitbook, and I have a number of issues with it:

1. I uses a non-standard format completely different from the Sphinx
documentation format that we are using, that is a well established
standard among Python projects.
2. The "support" for translations is basically just linking to different
language versions. There is no support whatsoever for actually translating
the content or for keeping track and updating of translations.
3. It requires creation of yet another account, in addition to the github
one, which is needed anyways.

In the mean time, the contributors to the readthedocs translations can
simply click the "edit on github" link, and edit the files right in the
browser. They don't need a readthedocs account, unless they are starting
a translation to a new language.

On Mon, 28 Nov 2016 11:02:31 +0000
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
> 
> 
> 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
> >
> >  



-- 
Radomir Dopieralski