Translating our userguides - take 2

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 :slight_smile:

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 :sob:

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:

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 :slight_smile:

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

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.

@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?

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?

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! :dizzy_face::cowboy_hat_face:

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

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).

Thank you @Rachel for this summary and having moved our accounts to free unlimited accounts :slight_smile:
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.

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 :see_no_evil: 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 :smiley:

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?

Ok sorry @Rachel I think it was not clear to me yes :slight_smile: 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.

@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

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
But I think this is a good thing. We should manage those domains globally with the global 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 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.

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.

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.