Translating our userguides - take 2

[Rachel]

I guess this post would have been better under How to translate and update/adapt the user guide in a smart and collaborative way? but this discussion started in January 2016 and I wasn’t sure if it would be clear to add something in this incredibly rich thread

As some of you know, I recently wrote to Gitbook in order to get unlimited number of users. They offer this to non-profit and open source project, so I’m pretty confident we will get it.

When Gitbook was chosen, this offer for non profit and open source was not available. As multi-language Gitbook are not live yet, this is why (correct me if I’m wrong) we have decided that each instance will have its own Gitbook.
In the light of unlimited user access, I believe we can make a better user of Gitbook “organizations”.

Let’s take a current example:

• Oxfam has someone ready to translate the guide in German. This is ace as it will also benefit the German instance
• In our current process, Oxfam has to create a Gitbook organization that will host the German user guide.
• Then they need to apply to the non-profit upgrade
• Once granted they will be able to invite Germany to collaborate

I see 2 downsides : this is a bit long to do and if Oxfam decides to stop the OFN project one day (I’m not saying they will, this is just a fake example) they would close their Gitbook organization that would lead to the loss of 2 versions of our guides

Anyway, now that it is possible to have as many user as we want, we could either:

A. Decide to keep one single Organization: The Open Food Network.
B. Create one organization per languages

In both cases, we can add members with written access.
This way the community keeps track and access of all translated version and updates are also made either : you can copy / paste more easily from one guide to another.

Option A.

With this option we would need to create a “space” for each guide. Just like we did for the Super admin and contributor guides.
This “clean up” can also be done on Github. Indeed, we could have all the language specific repos inside the Open Food Network Github organization.

I’ve done this for the Datafoodconsortium organisation. As you can see here:

Data Food Consortium

One repo is called “standarddocumentation”. This is the repo of the Gitbook. I didn’t create a new github organization to do this.
By having a single organization, we could have all the repos in one place and maybe make these guides more visible.

Option B.
This approach is a bit better in UX I guess because we create a kind of filter per language. In one organization we have all the “spaces” in the same language.
It will look like this:
When I update the DFC guide or the French OFN guide, I log in on my PERSONAL gitbook account and from there I have access to the French gitbook organization and the Datafood gitbook organization:

It is very easy to switch from one to the other.

What do you think? Is there something I miss on the current reasons why we have specific repos and instance approach? Thank you

ping @MyriamBoure @EmilyRogers @tschumilas @lauriewayne1 @lin_d_hop @sauloperez @Kirsten

[tschumilas]

Wow - Thanks @Rachel for researching this and summarizing. I am good with either option. I feel bad that I haven’t learned how to update the user guide as it now sits. I’d like to help - but this is ‘winter work’ for me. I will learn and participate in whichever of the translation options the community selects. I think that an organization instance might be better than a per language because some parts of the user guide - even with the same language - are still specific (ie: payment gateways ). Although maybe there aren’t many of those, and if we did per language, we could always speak to that in the guide content.

[Rachel]

@tschumilas just to be sure : you would prefer having your own English user guide rather than sharing the English user guide with all English-speaking instances?

[tschumilas]

I’m happy to go with what others think on this. Either way is fine with me - I’m just noting that if we share an English speaking user guide - there are a few (likely very few) spots where we would need to anticipate that. For example, payment methods, we would need to say: In Australia…, In CAnada…

@lauriewayne @lauriewayne1 what do you think?

[lauriewayne1]

I think just the one English version would be fine - easier to maintain a consistently updated guide for everyone and easily adapted where necessary (like payment methods). I also believe that it’s great if US users see references to other countries, because, hello Americans, there are other countries in the world!

[Rachel]

Gitbook has now upgrated both the French and English account with unlimited access.

To be more precise in what I’m proposing above: my initial proposal was not to choose between a user guide per instance or a single user guide per language. But of course if the community prefers a user guide per instance, my proposal can just be forgotten.

A way to rephrase what my initial post was saying: now that our accounts can have multiple users and guides, we could optimize the number of Organization accounts. There are 2 options:

1. creating ALL user guides (whatever the language) under the OFN Gitbook Organisation account (we manage access per users for each language). Downside: whatever the language would be listed as what Gitbook is calling “spaces”. Which can be crowded if we grow up.
2. We create / keep one organisation account per language. The “only” difference is that we have a clearer filter / access per organization if you look at my screenshot. Downside: we need one account per language and we need to ask for each new language a Gitbook upgraded access.

This is interesting in order for OFN to keep centralized and decentralized access to the different language versions. Today we only have decentralized, meaning if one particular user translate it, if this user closes his/her organization account, we loose the content of the guide (the organization is the owner/admin of the guide).

[MyriamBoure]

Thank you @Rachel for this summary and having moved our accounts to free unlimited accounts
I also think if we manage one user guide per language will be easier to maintain, and we can for sections where it’s instance dependent to specify for each instance by sub menu / sub pages. We can see when we move forward.

[Rachel]

thx @MyriamBoure Yes if everyone agrees on one guide per language, then we need also to agree on the next step, which is either:

1. A single Gitbook organization (with one space per guide whatever the language or the type)
2. A Gitbook organization per language (with one space per type of translated guide: super admin, handbook, user…)

Sorry if I repeat myself but as everyone replies only on the one guide per instance vs. one guide per language thing I just want to make sure everyone understand what I’m speaking about

This is important as Belgium is creating the German and Flemish versions of the user guide. I need to know where I tell them to store theses guides.
But if I’m speaking chinese here maybe a call would help. Let’s see if we have some spare time left on the global hangout tomorrow?

[MyriamBoure]

Ok sorry @Rachel I think it was not clear to me yes it seems somehow to complexify the thing to have one organization per language, as we need to request free acounts each time, and your resilience argument is also that it’s more “managed collectively, as a common” if it is in a common space.
So if we can, as I understand, organize a bit the UX by creating spaces for each language within a single organization (like you did for DFC within the Open Food France organization in Gitbook if I understand well ?), I would vote for that.

[Rachel]

@MyriamBoure @sauloperez Scrap what I’ve just said about customs domains in the hangout. You can assign custom domains to each space / user guide. So even if we migrate Katuma’s catalan guide into the OFN global account, the guide could still be available under https://guia.katuma.org/

However, Myriam, with the strategy we decided, a language could only be available under ONE custom domain. Therefore the French guide could never be under a custom domain like guide.coopcircuits.fr
But I think this is a good thing. We should manage those domains globally with the global openfoodnetwork.org URL. Of course if we want to manage custom URL in the first place… so far we don’t have a custom URL for the French one, and I’m not sure I see the need here, but that’s another topic.

To take the example of Katuma, if you do a Spanish version one day, it is possible that in the future someone in Latin America would start using it, but it is not sure they would be using Katuma’s platform. So a Katuma.org custom domain for a Spanish or Portuguese version does not make sense with what we decided.

If we want this we want instance specific guides.

[sauloperez]

It’s indeed something we should aim at sharing although I still see the need to adapt ithe guide’s content to the particularities of our instance. That being said, I don’t think we did any. Ours is just a translation from tve English version.

On the other hand, keep in mind that domain names can point to anything we want. So we could have some domains act as aliases if we need to. So to me is about how to share an organize more than anything.

[Rachel]

I gave it a try and now created two 2 organization within the global account. We now have Dutch and German organizations that can have several guides.

You will only see this when you login with the credentials in bitwarden. Otherwise, you only have access to the guide you are contributing on. For example Theo has access to the Dutch and German one, but not the English one.

I’ve emailed Gitbook to understand if this was the right way to go or if at some point we will be limited by the number of organizations and would need to have all the languages under the original organization.

I will wait for their answer to migrate the french one.

[Rachel]

Ok as I just did the process again to give access to the Turkish team it appears we cannot create any more organizations with our main account, or at least we cannot create new organizations under the same unlimited access.

So, the organization needs to be as follow:

The OFN organization is hosting all the guides. But admin/writers/readers permissions can be given towards members or teams per guides. So a maintainer of a particular language does not loose control over the content and can always decide to migrate somewhere else if they hate gitbook. I have created one team per language. The OFN global user (in bitwarden) has access to everything (so for English user we should really not use this account to edit content, to avoid mistakes ) so I arranged all guides by language thanks to the group function:

As the dutch and german guides were not written yet, I took the liberty to migrate them to the OFN main account and give access to the proper teams ping @Theodore

ping @lbwright22 @Kirsten @Jen @lin_d_hop

[Rachel]

French user guide in now up in the global organization as well Brazilian guide to follow. @sauloperez do you want us to move the catalan guide as well? It can give you access to gitbook with unlimited access.

[sauloperez]

Yes, please. Can you invite @Eugeni and I? We thought we should create a Spanish guide as we did with Dutch and German. There’s none yet.

Thanks for leading this!

[Rachel]

So with @Eugeni we have taken another approach thanks to new Gitbook’s feature of being able to create variants (which is Gitbook’s feature for translating guide).

So the Spanish version of the user guide is available here: https://guide.openfoodnetwork.org/v/es/

As well as the Italian version, which is now here: https://guide.openfoodnetwork.org/v/it/

You can switch from these versions in the right hand menu:

Pros: all translations are linked at the same place , we don’t need to chase to understand which are all the custom URLs used across the system.

Cons : Customs URL are not possible in this scenario. All translators are starting on the same space in Gitbook. Maybe this can lead to more errors? Like translating a page on the EN version instead on the local version.

Note: these pros and cons are really related to the user guide which has a strong instance-related aspect.
Hector has started to translate the contributor handbook https://ofn-user-guide.gitbook.io/ofn-handbook/v/es/ and I think is it really the correct way to translate such a doc.

The question we need to solve then, is what we do with this translation feature of Gitbooks regarding the user guide. Do we:

Option 1 - keep it and leave the choice to the translation team to choose whether they want a dedicated space in our gitbook or just a variant?

Option 2 - feel the error risk is too high and we forget about this feature for now?

Option 3 - feel that - as for the handbook - for the resilience of our translation it’s best to move ALL translation as variants of the EN guide and stop doing dedicated guides?

I feel on my side I would be ok with both option 1 and 3. I’m actually thinking it would be good to move the FR guide as a variant. As the software does not allow for 2 URL for the guide, only one. So easier for french speaking people in Canada to find out about the french version.

Thoughts? @lbwright22 @EmilyRogers @MyriamBoure @Bato @thomaz

PS: @romale if you want we can migrate your russian translation to the OFN org. It would allow you to stay admin of it but also adding as much people as you wish to help on translation. Nothing mandatory, just ping me on Slack if this sounds interesting for you

[EmilyRogers]

Thanks @Rachel for sharing. I like the idea of having the translations as variants, particularly so they’re easily discoverable by users.

I agree though, that there is some risk in editing the wrong version of the guide. I certainly found it non-intuitive, navigating between the three current versions (English, Spanish, Italian) as it currently stands in Gitbooks. Perhaps that’s because they are all mostly still in English, so it’s not immediately apparent which version you are looking at it.

It may be specially confusing right now as the first page on the User Guide (in all 3 versions) currently states ‘You are Reading the English Version’. So at the moment, I feel it would be a very easy mistake to make!

But I think once we get past the initial set up stage, and if we take care with training of new editors, then I feel like it’s something we can mitigate.

[thomaz]

Hi @Rachel, sorry for the late reply. I also feel that having all translations as variants is the way to go.

To avoid mistakes, maybe one solution could be to move dedicated space translations to the Master version ONLY after they’re have been completely (or sufficiently) translated? Is that feasable?

For example, the portuguese version has its dedicated space and is less than half-way translated. Maybe it shouldn’t be moved just yet, while there is a lot of work to be done.

By the way, we were about to kick a new portuguese translation sprint but @Kirsten suggested that we left it on hold as there could be some major changes on the guide, very soon. Is this still the case?

[Rachel]

Hello @thomaz about major changes, I don’t think there are any in the pipe, but maybe @lbwright22 or Emily can confirm?

About transfering, I haven’t assest it completely yet, so I’m not yet sure how to transfer a space into a variant. Maybe the only way is to copy paste. In that case, transferring can become quite a headache…

Will let you know!

[thomaz]

Thanks, Rachel. I guess the the ‘major change’ was the one Louise has just made after the latest deploy, so we can begin working on the portuguese version now.

I’m trying to think of a solution to export / import content from one space to another. My best guess is the ‘import from url’ option, but that is limited to 20 pages.