How to translate and update/adapt the user guide in a smart and collaborative way?

Thanks @MyriamBoure. @NickWeir and @lynne , I would love to hear what you are planning in terms of a UK user guide?

Is there an issue with different countries having different styles/quality user guides?
My thoughts- users will only ever see the user guide material of their country, so maybe it doesn’t matter if each is different and inconsistent. Some may be Wordpress, others discourse. Each instance should strive to have a basic user guide available, but if some are more up to date than others… this is probably inevitable, and not a big problem, so long is it meets basic standards.
Perhaps each time an instance is created they can have an existing guide imbedded in their site. Depending on if they want discourse or Wordpress, they can copy the Aus/French/Norway/Etc guide as a starting point (whichever is closest to what they want). This is a starting point and from here they must then customise it (content and translations). Or they can opt to make their own guide in a totally different place and just refer to existing ones as they build it.

Process for updating user guides if they are not interlinked
I was thinking, that while the ‘notification’ idea is great, if I get a notification that Norway has added a new page, I won’t be able to understand it anyway, so will need to ask you for a description. I think conversations around updates may be unavoidable? If we have independent user guides, we could have a group on the global discourse where all user guide maintainers can track and discuss content changes/additions? For example, at the end of each sprint I’ll add a post describing new features and link to my rephrasing in the aus guide. If in France you add a new page, you can put a description of it in the thread, in English, and a link, so others can also add this content if they wish. If the UK develops a feature, they can describe it here so other instances can add it to their guides. This way it is not centralised, anyone can offer additions. And if one country falls behind, they can always come here to see what they need to update.

The end of the global user guide?
This conversation has got me thinking about whether a global guide is necessary. Currently, an instance may use the global user guide in the very early stages, but my understanding is that as soon as they grow, they will need their own guide, as is currently occurring for Norway and the UK. Am I correct to say that we don’t really need the global user guide? Without it, instances who are just budding can refer to existing, up to date user guides (such as Aus, and soon UK, Norway, French), whichever is more relevant to them, and in a language they know. When they create a new instance, part of the setup will be making a guide.
Currently Australia’s user guide is the global guide. However, we try not to put Australian-specific content in here (although there is definitely some). This is not ideal for Australia, because it limits the Aus-specific content. Therefore, one day, we would like to move that user guide to our instance site (so it’s easier to find), and make it Aus-specific. This would probably be the end of a global user guide, because maintaining both is too much work.

Hi @sstead!
I personnaly agree with all what you said :slight_smile: I like the Discourse user guide group, I think that can work like that.
And I also agree that this means there will be no global user guide.
I’ll let you know when the French user guide v.0 is ready and we can start piloting the process :wink:

Friends from offered help with translating User Guides to spanish (we start working together on setting up .mx instance). Do we still need to find a workflow for it? How about just giving a try to

Hi @elf-pavlik!
Actually we had kind of a lazy consent from what I understood, that each instance would choose the tool they want for their user guide. For exemple in France I’m doing it on the local community forum, I created a category on Discourse:
So I’m in the process of translating every page from the Australian user guide, and we have a channel on Slack #user-guide where @sstead share the updates on the Australian user guide… Actually Slack might be easier than Discourse, but now I see you proposed Discourse Sally so that we keep track maybe of the change? I don’t know, for me Slack is ok to start with :slight_smile:
I wouldn’t use Transifex, as from my experience we need more adaptation sometimes than just translating…

We have not had the time to dedicate to translating the user guide to Norwegian yet, but as we are also now going to need Swedish (and later Danish/Finnish) I have been looking at potential solutions other than discourse for our needs in Scandinavia, with a preference toward enabling other instances to opt in as well.

I really enjoy the user guide as it is, and find the user friendliness to be of great importance. @sstead gave me access to the wordpress site, and I notice that Avada is the theme being used.
Avada 5.0 recently came out, and I personally love it (but agree that it is not the most user friendly solution for the back-end, nor easy to hand off). But I looked into whether or not there are options for translating from there that would make for an easy way of managing one global version for those instances that do not want to start from scratch with a discourse version.
There seem to be some options available to manage the user guide using WP, including the transifex option that @elf-pavlik mentioned above, as well as the polylang option that @sstead mentioned.
another one is:

Avada is both polylang and wpml compatible.
We could choose to only translate the user guide pages or we could move the user guide as a standalone in its own install, a import/export of the user guide pages should manage that without too much trouble. It can easily be linked to from the current wordpress site and embedded so that it is virtually seamless on the front end for the .org site.
By having it as its own standalone installation, we do not risk messing up any other work on the WP site, we can track the changes and modify when needed. Each instance can link to their version of the user guide, and new instances can come on board as they wish.
We can open up to allowing comments on the pages for feedback and discussion or even include the avada ‘forum’ for a discourse style discussion all integrated into one (with or without social login). The forums can also have child forums.

I have only just grazed the surface on this, and I know that it is a lot of work, but if there is anyone else interested in going down this route, maybe we can find a solution that works well for everyone.

ping @MyriamBoure @sigmundpetersen @danielle

Hi Cynthia, I don’t have much experience with multilingual web pages, so I’m happy to take your advice regarding the tool. I wonder, for your proposed Avada solution- what does the user see when they arrive at the guide? Is there flags in the top corner reflecting the language they can select? Or do they select their instance, which then has different languages within in? For example, we don’t want French speaking Australian’s to read the French guide, as it might have different content? Does this option allow for translation of text as well as different content between instances, such as some additional pages that are only visible to a certain instances? I like the idea of removing it from the main Wordpress, because you may be happy for someone to edit the guide, but don’t want them to be able to change the whole global site- and I don’t think wordpress has page specific roles/permissions.

@sstead I will have to look into it some more and compare the various options, am no expert by any means!
I would imagine that a simple structure would allow for a main menu that drops down via instance and then languages for that instance. The french for Canada will vary tremendously from the version in France, as will the english versions. Every thing from tax issues to business model.

We already are going to see issues on transifex with languages, as some of the content that used to be managed in the super admin configuration is now moved to transifex (specifically business model info)

I will look into it when I get a chance, anyone else who is keen to discuss, feel free to contact me :slight_smile: will gladly brainstorm on a video call.

Is Canada the only instance still using the Australian (by default global) user guide? I confess to being overwhelmed at the idea of making our own user guide right now. For us now, we are only in English Canada so translation is not an issue (yet). Yes there are a number of ‘terms’ in the Aus guide that are different from what we would use - but frankly - its less work to just explain to people that 'that is an Australia term for…" than to do our own user guide. I also think that for a new instance it makes sense to have some user experience first - and then its possible to pull a team of users together to adapt the Aus (global) guide. So - I want to ask other instances - @MyriamBoure @CynthiaReynolds – if language was not your issue - is there a reason you would prioritize creating your own instance guide? (Maybe I’m missing a good reason.)

Also - I LOVE what you’ve done @NickWeir with the US enterprise guide - it very usefully builds on the user guide. I could see doing a document like this for Canada before making our own user guide. Can I keep using the Aus (global) guide forever? :wink:

So far in my opinion, the Aus user guide is doing a VERY good job for users in England and Scotland. However we are now going for funding to go bilingual with English and Welsh and this has made me think that we should consider including translating the user guide into Welsh as part of this funding. Interested to hear opinions of this from @lin_d_hop and @mags - it would increase our translation costs dramatically…

No harm in getting a quote to see how much it would cost to translate into Welsh. The problem would be the ongoing work to update it in Welsh each time the user guide was updated or changed. But after the bulk of the work was done we could try recruiting a Welsh speaking volunteer to help with future additions!

@tschumilas I think the main reason for us having a local version of the user guide is language :slight_smile: And also I think one thing I wanted to experiment is having a more “community version” of the user guide that enable people to ask questions if something is not clear and other people can answer, etc. So that’s why we are building up the french user guide into discourse directly… it takes a very lonnnng time to translate, I’m still not done with it, doing bits by bits :wink:
What is the “UK entreprise guide” you are talking about?

@MyriamBoure We have a rather loose collection of documents and information relating to how to run a food hub which we’re trying to work up into an additional resource for OFN members. It doesn’t relate directly to the platform so we’re keeping it seperate from the User Guide. At the moment the plan is to encorporate this into the UK Discourse, but maybe also make PDF guides that can be emailed and printed off if need be.

@sstead I have been doing some thinking about how to move forward with the translations on wordpress.
We have a few options, and I have not sussed out all the details, but wanted to share this potential option.

The current website is using an older version of Avada. We could upgrade it and try to do it all there using (demo video here). I would be hesitant to do so until it has been upgraded, and I can testify that Avada 5 is a dream to work with but have not gone through the process of upgrading from an older version and hear that it can sometimes cause glitches. If upgrading is not something we want to do, we could export the user guide and set up a separate install (would require a 60$US avada license and hosting) set that to a subdomain and link from the original site to have seamless integration in menus, as well as direct links from instances.

I have applied for a non-profit license at and having seen their comparisons here - think we should look at this over polylang and then decide on whether that is a better option than transifex.

The beauty of their module is that translators do not need to know how to use wordpress, and can manage the content separately see here.
You can also have an overview of the status of translations see here . When you make updates to the user guide, it seems like a reasonable method of sending segments or pages to the translation job list for us to update.

It is not a small task by any means, but looks like a good way to move forward and is scaleable. Manual changes to screen shots for the different uses is able to be done with a bit more wp knowledge.
One issue I am trying to wrap my head around, is that we are not only translating content for different languages, but for different instances. Example: English language will have a variety of different needs for tax or other instance specific requirements. Uk/Aus/USA/Canada all will need their own content in the long term. It could be managed using menus, but I will have to see if there is a better option. Anyone else who has a better idea, please let me know! :wink:
one option: making the content global with language translation and a dedicated page with each instances ‘instance specific’ information easily linked to the main content.

@MyriamBoure - you have mentioned that you would like a more interactive method to enable discussions. We can easily add a dedicated forum for each instance. Like a light version of discourse and does not require hosting. Super easy to set up on Avada via bbpress and will cost us nothing.

The wordpress site is also a perfect place to manage the repository of documentation that will be coming along, and @mags this would be a simple solution to include your documents - and if they are set up as pages, they too can be translated using the same solution.

I welcome feedback on this.

I support this path strongly :+1: :slight_smile:

1 Like

Thanks @sigmundpetersen I also just chatted with Caleb at Transifex, and he said that since we are already on the free open source plan and that this is just an extention of our content that we should just open a new project under the same account and mark it as open source. Maybe we should also look into this option and weigh the pros and cons. If anyone else has thoughts on this, feel free to pipe in with some guidance :slight_smile:

I am not sure which will be heavier on the workload wpml or transifex, but given that we already have a system for using transifex, there is a benefit to not having to introduce new solutions.

It should still allow is to include the forums for each instance to enable discussions.
Will have to consider the user interface and see which will be the most appealing.
ping @danielle any thoughts on this?

Maybe we don’t have to choose. WPML and Transifex now works together :slight_smile:

LOVE IT! ahh… thanks @sigmundpetersen
ok, it looks like we now have a good idea as to what the tools are, now we just need to plan it out (and potentially get funding - what else is new :wink: )
I am open to having a hangout if anyone else is, or we can include it in the global hangout agenda.
ping @sstead @MyriamBoure @danielle @NickWeir and anyone else - - feedback welcome

Sounds like a good solution @CynthiaReynolds, well done! Some thoughts going forward which you’ve already touched on…

  • Evada update- What kinds of glitches might we expect and how can we manage them? Will we need costly devs to help, or can wordpress amateurs like myself iron these out?
  • New URL? What will be the landing page? Can you link to the particular language, so that Australian users don’t even see the other languages (to minimise confusion)?
  • It’s a shame that there isn’t potential for English x 4… UK, Aus, Canada, US? And French x 2 (canada/france)
  • We’ll need to work out the best solution for instance specific content if there’s no way to create instance translations… I’m sure there’s something we can do, maybe expando collapso segments in the global guide covering the instance specific info for Tax etc?
  • Will updates be handled via the initial strategy- whoever makes an update describes this in Discourse? Or can to tool flag certain parts of a page for translation? Is there automatic ‘new content to be translated’ notification? If not, what’s the best way to manage updates?
  • Looks like adding in translated screenshots might be a bit fiddly, each translation will need one person who’s comfortable doing this in WP.

Thanks @sstead :slight_smile:

Re: Avada update. Not having been part of building this site, I can not really say how it will react to the upgrade nor how the other plugins will react, The Avada 5 upgrade focuses on the Fusion Builder which is great to work with, but may cause some issues based on the build of various features. I am not an expert by any stretch of the imagination, but it does seem that Avada support are very helpful with getting everyones issues taken care of during the transition, and they also have a great user group on facebook who are all very helpful with support issues. I imagine we can contact support in advance and see if they can let us know if they think our site will upgrade without issues. Should save us a lot of hassle by asking in advance and we could ask them to have someone available to help out if we need. Doubtful we would require any dedicated dev on our end unless you did some special dev on the site already that is not in line with the theme out of the box. We can of course look at a separate WP install and hosting for this which would allow us to work offline until it is ready, leaving the current functionality intact.

Re: URLs. we can set each instance as their own subdirectory or subdomain (I prefer subdomains personally) It appears that Transifex will also help us do this :slight_smile: The ideal (I imagine) is that each instance has their own content based on the global contents and available in the languages they need.

Re: multiple languages, we may just be in luck! I was looking at the available languages (and the ability to create new languages) and they already have English (UK) English (Canada) and English (Australia) !! whoo hoo, did a little happy dance when I saw that. French is already available for Canada and France and they even have both norwegian languages (yes, we have 2 official versions) This means that we could in theory have a seperate language for each instances needs and if we need to go beyond that, we can create a new language as well. I also saw ‘Pirate English’ so me thinks we are good!

Re: Updates How we manage the updates is definitely to be determined. My understanding is that when content is changes on the core language that others are referenced to, they will show in transifex. If this is the case, all new updates should be made on the global core guide and trickle down to all other instances for translation as it does on the platform. If an instance wants to update their guide, we should have some sort of process to notify and update the core version to enable the spread of information. I may easily be wrong here. We may want to look at creating a global core language version which is a copy of the current AUS version, modify it to be more neutral to each instance and then enable translations from that. (hope that makes sense)
How we handle topics such as taxation etc is still an issue, more so because of screenshots etc. They need someone who understands Wordpress. Let me know what you think about that and how we could manage it. I haven’t really looked into our options yet.

We can also set up the forums - one for the userguide in general, with child forums for each instance. The forums can be added to the landing page for each instance if that is of interest.

In the long term, we will need to consider if every instance will have their own wordpress website with links to the user guide, their own ToS (which we are currently working on), mission statement, governance, by-laws, projects and other information, all of which is only pertinent to their instance; or if we want to consider truly making the .org the manager of all content and be fully multilingual.
In Scandinavia, we have a very basic WP website to provide information about our instance, due to lack of funding and other priorities, I have not been able to dedicate more time to it, but hope that at some point I will be able to.
Given that each instance will develop differently due to funding, focus and features (thinking about examples like the Thrive project Connect & Learn) we may want to lean in that direction. (Interesting concept: setting up a basic structure WP theme for new instances to help get them over the hump)

@NickWeir @lin_d_hop would love to hear your thoughts on this.