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

International
1

Hi everyone,

Following the conversation: User Guide as a distinct project with its own worklfow

There are more and more language communities around OFN as new countries set up OFN instances. With that comes the necessity to translate the user guide, which is today on the openfoodnetwork.org website, and managed and updated by @sstead.

That’s a great tool and very usefull (thank you @sstead for the great job!), but we have seen that in France for example, with the first beta testers, we sent them to the user guide, and the tester wrote an email to the australian team because it was the email indicated in the user guide :wink: And anyway, not so many potential users of the OFN in France will speak French, so we need to translate the user guide. Same for Norway.

With the translation may come also some adaptation of content, for example the way we manage VAT in Europe is different from the way we manage it in Australia. And maybe we will create one more page here or there because there is a topic that is not clear and has not yet been detailed in the Australian version.

So to kickstart the converstion: how can we manage that? So that we can collaborate on that and not each instance build its own user guide on his side… For example that would be great if Sally modifies something (because a new feature has been implemented for example) that the other language moderators are notified so that they can make the change in their language. And also that would be great to make it easier for the new instances joining to find a space where they can do the work, a bit like @maikel has done with Transifex, now any new comer can request a new language and start translating…

My first thought would be to have a wiki (because wikipedia seems to work a bit as we could work, you can create a page in one language, other people can translate (and adapt?) in other languages, and I guess when someone make a modification in one language I guess (?) it notifies the other contributors in other languages…

I saw it seems possible to create a family of wikis in Wikimedia (tool used by Wikipedia) and that could potentialy work.


I saw there is also a wordpress plugin that can be used to add a wiki to a wordpress site, Userpress… but it doesn’t seem to handle multilingual wikis…

What are your thoughts on that?

Ping @sstead @danielle @marito59 @Selmo @alvarosaco @NickWeir @nickwhite @CynthiaReynolds @sigmundpetersen

PS: if the Australian team doesn’t have time to investigate on that, I guess we might find volunteers to test different options :wink:

2

Thanks for starting this Myriam, below are my thoughts about having translations.
Sounds like there are 3 things we need:

  1. We need the user guide translated into different languages.
  2. We also need some modified content in different countries (ie different versions of the tax related content for different countries, and links going to the correct local instance, not always .org.au).
  3. The current user guide sits in the global site, but perhaps we want to move towards each instance having their translation/content on their local site.

In terms of the technology we use, I’m definitely not the person to ask. Here are my current thoughts about Wordpress:

  • It has a lot of flexibility, but this comes at the cost of complexity
  • It’s not very user friendly. It’s difficult to hand over to other people, because it takes time to understand, unless the person has experience using Wordpress
  • It’s quite time consuming to change content. Simply because even changing one spelling mistake can take many clicks
  • The finished product looks relatively sleek (compared to something like discourse) and is quite user friendly. I believe this is why we initialy chose Wordpress, a guide is no use if users think it’s too ugly and don’t want to read it.

This was one link I found which may be an option for translating the current Wordpress site - http://www.wpbeginner.com/beginners-guide/how-to-easily-create-a-multilingual-wordpress-site/

My current user manual update process:
When new features are released I’ll go through and update the user manual in the relevant places. This might be just after a feature goes to production, or when a new version is released. Because there are duplicate pages for many features (the hub/producer guides are separate) one feature might require mentioning in 2-3 places. Once the user manual is set-up, I would say it takes me about one full day each month to maintain.

Requirements of a translator
I think the translator would need to have a decent understanding of the OFN. Many words and terms used are OFN specific, so it could be difficult for an intern or someone fresh to the OFN’s terminology to do the translating. For many features, if the translation is late, the out-dated content will still largely make sense. So there is not too much of an imperative that it’s done immediately, but we want to avoid some translations falling out of date, so would be ideal for each language to have a designated translator.

How could the updates be communicated?

  1. I could make changes to the English version, and then flag this change with translators, so they can see the exact phrasing and simply translate.
  2. Or I could give each translator a list of the features that have been released, and they could add the text to their pages themselves. In addition to this, I could mention the pages where this feature will need updating and link them to my explanation as an example (so they know how the feature works).
    Q - When something goes to Australia’s production site, does it also go the to the other countries’, or not until the new version is released? Translators might need to wait until their instance is updated before changing their user guide.
3

Thank you @sstead for your precise input :smile:

I spent some time thinking about it and trying to figure out how that could work. From what you said, I see 3 options:

1- Have a dedicated multilingual wordpress website for the user guide

This website would be “copy” of the user guide part of the Australian website, and we would use the manual translation plugin to allow other translators to make the version for their local instance.

GOODS:

  • it’s easier for any new instance to quickly translate and adapt the user guide
  • the user guide will more likely be consistent from one country to the other, without too much differences in qualities, etc.
  • I’m not sure if, when there is a modification in one language, there is any notification to the other moderators on the other languages… if yes, then that would be a very good aspect of this option.
  • The front end is pretty user friendly

BADS:

  • We need to choose one translator and this role cannot really be distributed.
  • Wordpress doesn’t allow people to discuss, ask questions and comment on the user guide, so people have to go to another environment, Discourse, to ask questions if they have (not very user friendly to ask to change environment)
  • I’m afraid it might be a bit confusing if we have all the languages and people have to click on their languages, as there might be content adaptation as well linked to the languages. For example, if you are an English speaker, you live in Australia, but you clic on English (UK) because you don’t see any difference, you finally don’t have the content for the Australian instance.

2- Have a dedicated wiki, with a family of wiki, for the user guide

This wiki would be under for example userguide.openfoodnetwork.org, with each instance/language being able to send their users to their dedicated space

GOODS:

  • can have multiple admin
  • people are used to navigate in wikipedia :smile:
  • we can get notified when a modification is made in one of the family of wiki (should check, I’m not 100% sure)
  • pretty easy to set up for a new country when we have put everything in place I guess

BADS:

  • new environment to get familiar with
  • another enviromnent for the user, who already has to get familiar with the OFN interface and Discourse
  • need to dedicate a bit of time to set it up
  • Autralia would have to decide if they want to move their user guide in this wiki or not

3- Each instance put the user guide on his own local site (using wordpress or whatever) and we have a manual process as you propose for the modification.

GOODS:

  • Each instance really think for his local public and try to find the best solution adapted to its local communication strategy

BADS:

  • as we are beautiful humans, and not machins, there is a risk that with the time passing, the various user guides in various instances might become more and more distincts, with some user guides being well documented on this aspect, but the information didn’t circulate well about this modification, etc. Maybe that’s not a problem, as it’s the responsibility of each instance to manage its user guide.
  • It can potentially take more time for a new instance to set up its ow user guide
  • Depending on the tool chosen, it can be less user friendly

For France & Norway, I was thinking we could potentially use Discourse for the user guide, for 2 reasons:
1- It’s better not to ask the users to get familiar with a 3rd new environment. We already have the marketplace site (main site) + Discourse (for question, sharing good practices, discussing about our local governance)
2- As many questions that could emerge in Discourse might be related to some misunderstanding/lack of information in the user guide, maybe it’s actually better to allow a discussion to happen on every user guide page. So that we know in real time if something is not clear enough and should be explained differently, or some tutorial is missing.

So I was wondering how this could happen so I tried in the SandBox Discourse (sorry I did it in French!):

discourse.png583×751 27.4 KB

What I imagined was have a dedicated Category for the user guide, where the ability to create a new topic is disabled (https://meta.discourse.org/t/disable-creating-new-topics/28018) to avoid new awckwards pages poping up in the user guide.

  • That first page above would be the “table of content” (we can make it more user frendly with pictos, etc.). I took exactly the same pages as the Australian user guide, just translated the titles.
  • Each page would have a URL link redirecting to the correspondant Discourse page, basically, one page for each page of the user guide.
  • The good thing I see is that it would allow people to comment directly on the user guide page if something is not clear, so that one of the admin car very easily, without having to learn how to use wordpress, update the content of the user guide.

It actually gave me an idea for a 4th option…

4- couldn’t we setup a parallel Discourse as community.openfoodnetwork.org, could be userguide.openfoodnetwork.org ?

Ideally if you are logged in OFN or the community Discourse you would be automatically logged in

  • In this Discourse we would have one category per Instance & language (so the instance can link to that category / those categories, either from his own Discourse, or from his website) EX: UK - User Guide / France - Guide utilisateur / Norge - Bruksanvisning…
  • The setup could be something similar as I just discribed above.

GOODS:

  • all admins could be able to update a page of the user guide pretty easily as we all use Discourse
  • we would see in the “unread” board if a modification has been made on a post in another country, so we would be able to adapt, in our own country, if we think the modification also apply to our instance
  • no need for a manual process to notify translators
  • the modifications can come from anywhere and everyone will see there has been a modification (if I change something in a page to clarify one point because we had lots of question, Australia can see that and say “oh, why not?”)
  • It’s very easy to start your own user guide as a new instance (just duplicate the pages and translate)
  • we allow our local community to comment on the pages of our user guide

BADS:

  • Autralia would have to decide if they want to move their user guide in Discourse or not
  • We have to check if that’s possible to be automatically connected to this Discourse when I’m connected to the French Discourse, the UK Discourse, etc.
  • We will have to work to make a very user friendly version with Discourse, but I think with having a table of content page and only links from that page, and putting some images, etc. We can make something beautiful… and I would be happy to contribute on that!
  • It’s another Discourse and there might be confusions from the users about the local Discourse and the user guide Discourse

Any comments on all those options?
@CynthiaReynolds @sigmundpetersen @Selmo @sstead @marito59 @nickwhite @tschumilas @NickWeir @gnollet

4

@sreeharsha @Biji_Karunakaran @Venu @alvarosaco @lawrence

5

I think it would be important maybe to make “proof of concepts” for those different options… I let you react, but I would be happy to build some proof of concepts to help us choose.

6

Hi @MyriamBoure :smiley:

I spoke with @sstead today and we both thought it was a great idea to build a proof of concept. You were right in the discussion at yesterday’s Global Hangout about this being something that is really needed for other instances (especially so for those not in English). So we’ll take your lead on this, and assist how we can while you sort out the proof of concept and create something that can be played around with based on the requirements we have.

In terms of those requirements, the only one that I can think of that’s important from the OFN Australia perspective is to make sure that we’re not impacting on @sstead’s workload without whatever solution chosen. The functionality you spoke of where editors are alerted whenever a change is made by @sstead to the main version, and for those editors to be able to see where the changes were made, would be a perfect way to ensure this.

@sstead may have additional thoughts on requirements, though her input above covers a lot of them.

Cheers!

7

Awesome @danielle!
I just need to figure out how I can install a Discourse to be able to make the proof of concept.
@gnollet I know you are working on that for France, maybe we can talk on Friday to see if that’s easy to duplicate the work you are doing so that I can play on a dedicated Discourse for the global user guide. I need to install a dedicated Discourse to be able to simulate what I have in mind for the user guide…
Let’s see!

8

@danielle, @sstead I made a very first proof of concept thanks to @gnollet who installed a Discourse for that purpose :wink:
So here is the link to the Discourse that could be under a “userguide.openfoodnetwork.org” http://testforum.cloudapp.net/, but only the admin will actually view the last modifications page.
Each instance will share only the link of it’s own “table of content page”, in its own Country / language category, like for example: http://testforum.cloudapp.net/t/table-of-content-user-guide-australia-english/14 (we can add some pictures / title banners to make it a bit more beautiful.
Thenthe user just follows the links. I just copied/pasted some info from the first 2-3 pages of the current user guide (didn’t do it all properly, just did it in 10 min;-)).

The idea is that:

  • all the instance user guide contributors will see when there is a new topic, or a modification on a topic (so they can see if they need to change something in their own)
  • users can comment directly on the page if they have question or something is not clear enough (they don’t have the possibility to create topics themselves)
  • if a new country/language want to translate & adapt the user guide in their language they can easily just copy/paste all the pages and translate

What do you think?
@CynthiaReynolds @marito59 @sreeharsha @Biji_Karunakaran @lin_d_hop @NickWeir @nickwhite ?

PS: we only have access to this test server for 2-3 weeks, so would be great if you can look before :wink:

9

Thanks for fleshing out this option @MyriamBoure Myriam! And @gnollet nollet for setting up a discourse.

I have a few questions about having all of the countries/languages in the one discourse, with each taking a category. I suppose this is necessary so that everyone gets notifications of additions/edits? However I have some concerns about this:

  1. With the discourse integration for each instance that Maikel was recently created, it seems like this would be a more logical place to put the user guide? Rather than having 3 discourses that a user would visit (global, user guide, local integration).

  2. I’m worried about navigation. Ideally you would want users to be sent directly to their local table of contents page, and as it occurs currently, they could progress through the topics with hyperlinked ‘NEXT’ and ‘BACK’ buttons… But will there still be the possibility for them to get ‘lost’ in the discourse, and accidentally walk into user guides for other languages/instances? For example if they click the icon in the top left it takes them to the home page, here they will see other guides? Also if they search for something will they see results from other countries? One potential solution, is that we can create ‘groups’ for each country, and each instance guide will be a category, which is locked to be only visible to members of the correct ‘group’. Then only people in the Norway group can see the Norway guide. But I’m not sure how we can add people to the correct group automatically? Also, this may make it impossible for those who have not signed up to view the category.

As an alternative, could we have separate discourses for each country? To get notifications, the person responsible for updating the guide for each instance will need to be a member on Australia’s discourse. They will need to set their notifications so they are notified of any edits/additions. However, I don’t think it’s possible to get notifications for edits. See bottom of this page -https://meta.discourse.org/t/email-notification-for-edited-posts-in-mailing-list-mode/16931/11 . If so the person making an update to a feature’s description will still need to flag people. But I think “whispers” could be an answer to this- whispers are threads attached to topics that only ‘staff’ can see.

Making the site more visually appealing and user friendly would also super important. It seems to me that within the basic settings you can change the colours and a few layout options. But if we were to use it for the user guide we would need more advanced customisation I think. To change the font and define H1, H2, H3 etc. I haven’t been able to find a sidebar menu in discourse, but that would be handy for navigation. And make the top menu branded more like OFN, so it doesn’t look so unfriendly.

Overall, I do think discourse is easier to learn, easier to edit and easier to track changes than the current wordpress version. It’s a good option. It would be a time saver to use discourse, but it MUST be user friendly, people are already feeling confused when they approach a user guide, and if the guide itself causes more confusion they are likely to give up, or not use it and just send us emails.

10

Thank you @sstead for those details comments.
I agree with you that each country having it’s own discourse is easier (and I had not thought about the connection issue, that they needed to log in a different discourse again)… I’m not sure about the process to keep all the user guides updated, but maybe it’s just the responsability of every local instance to organize themselves in that sense… I thought that it would have been great to find a way to be more aligned with the different versions of the user guide but it might just be too complicated for now…

I’m not sure either about the process for updating… I think we should avoid a centralized process, and it can be interesting if I create a new page in the French user guide for example to notify the community because it can be an inspiration for some other instance who might realise they also need that page… The Australian Discourse today is mixed with the global Discourse, am I right? So what you mean is that by updating the Australian user guide the other local instance managers will receive a notification (or will be flagged somehow).
I think it could work of course, but will prevent the community to get inputs from the other instances :wink:

Anyway I don’t clearly see another proposal now… and I have an open question: is it a problem if the user guide quality is different from a country to another?I guess every instance manager is supposed to take the responsibility to update the user guide each time a new release is done locally… so maybe it’s just fine if there are disparities between the user guides… what do you think?

About the design I’m not the best at it and don’t know what are the possibilities with Discourse. I think we’ll start just with a dedicated category on the French Discourse and will see with user’s feedback :wink:

11

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.

12

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:

13
14

Friends from http://nuup.co 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 https://www.transifex.com/integrations/wordpress/

15

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: http://forums.openfoodfrance.org/c/guide-utilisateur
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…

16

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 wordpress.org 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

17

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.

18

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

19

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:

20

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…