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

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.

thanks for all the work on this. Having a Welsh language version of the user guide is a lower priority for OFN UK but it is still on the list! I am happy to talk this through in the global hangout on 13th Dec. will this be soon enough?

hi all - slight aside to this thread but related to user guide

I am not sure if the proposal above is going ahead, but I just want to raise a concern about the current structure . .

in responding to this post about buying groups, it made clear to me that we might need to revisit the user guide structure / platform. It’s full of utterly awesome content thanks to @sstead, but its hard for me to find things even when I know that they’re there somewhere. It would be pretty amazing to have something with smaller linked pages that could be tagged or searchable. I know that the balance between book-like structure (with next / previous) and loose taggable has always been a problem, but I just wonder if it would be worth another look before a major overhaul of the wordpress. If this is not a problem for others just ignore me. Perhaps it could be resolved by breaking things into smaller nested pages and making it searchable?

I’m just going to throw this out there, but might using something like Gitbook be worth considering? The benefits I could see are:

  • Content is versioned so could be setup to match with versions of OFN.
  • Its Markdown which is plain text and the same format as Discourse.
  • It offers a great clean interface with a ToC and quick searching. See and for examples.
  • Multilingual versions are supported.
  • There is a plugin that could support tagging.
  • There is an editor app that can run locally for content creation.

All that said, I completely appreciate it isnt WP, which may be a strong “pro” for content editors. Just a thought.

1 Like

wow yeah, that’s really nice and clean - I think it should be a consideration . .

I’ve been thinking a lot about the user guide and related tools/help for new users - and my comments come from the perspective of getting Sally’s help to to first train myself, and now orient/train others - as a non-technical person. First - the guide is awesome - and any time I’ve taken the time to go through it step by step, it has worked like a charm. BUT I very seldom did take that time (sorry @sstead) - and I’m finding people I am now ‘on-boarding’ don’t take that time - instead asking ‘Oh - yeah, I saw that there, do I need to go through that?’. :wink: I was the same. I expect that something is intuitive enough that I shouldn’t have to read a guide. (likely not a reasonable expectation, but nonetheless, it seems to be the user expectation here in Canada anyway.)

So - I’ve wondered about a set of ‘tip sheets’ - that basically extract from and link to the user guide - but that are also ‘stand alone’. They would be focused on different user cases. So for example: 1. a farm shop where you only sell your own goods, 2. a farm shop where you also sell a few other products, 3. an online market/hub where you have many suppliers but only one pick-up point, 4. an online market/hub where you have many suppliers and multiple delivery sites or days, 5. a buying club where a group of consumers are collating orders … Each ‘case’ would have screenshots and step by steps (again - drawing from and linking to the user guide - but supplementing with more screenshots.) So - it is like a user guide pulled apart into use cases.

I also wonder if people’s logical process occurs in reverse of how the user guide is layed out. (I"m not sure - wondering what others experience is). I have found that people think about the shop front and the order cycle first - and so I get new users without fees and payment methods set up who can’t figure out why their shop isn’t working. On my calls/emails to them, I find myself working backwards from an order cycle.

All this to say that the user guide is amazing - it covers everything - but I can’t seem to get people to use it.

As a next step - I thought I"d prepare some of these 2 pager ‘use cases’ and share them just to see if they might be helpful.

A common pattern with docs like this might be to have a Reference Guide that covers lots of detail (mostly what there is currently) and then there could be a set of Tutorials or Quick Start guides for different user groups as you suggest.

BTW, Gitbook also supports comments from others, so that opens up a means for feedback, etc.

@Kirsten if it would be helpful I’m happy to setup a test book, if others think worth exploring.

Hey all I agree with critiques of the user guide and am open to exploring Gitbook

I think Gitbook is a brilliant idea and much better than overhauling WP :slight_smile:
note: the free version of Gitbook for open source projects has a limit of 5 collaborators

Perhaps one key decision if Gitbook is used is whether the book content is stored in a GH repo inside If that was done, anyone who has permission to commit to that repo could add content. Gitbook will sync changes and also push changes back to GH that were committed direct to the book. See So the 5 person limit is not too serious.

1 Like

So if we used github for this - would this still appear seamless to the new user in OFN? I mean would it still basically be a link to the user guide as it is now? (apologies for the obvious question again - but I just want to make sure new users don’t have to go to a different platform for the user guide - because they won’t bother.)

Yes, it would be a link to a guide that would look similar to the examples above (e.g. that could live at Just a set of web pages to read, only editors would need to know it is hosted on Gitbook/Github.


I understand the interest of GitBook and would definitely be open also to it. In France we have translated part of the user guide into our discourse, as I thought it’s already hard to get people on one tool, so I wanted to have it all there… I liked also the easy way to comment the guide. But being realistic, I also do realize that people don’t use it and prefer calling me and asking me the questions :-o

So I like your approach @tschumilas the ideal situation would be that the website is SO intuitive that there is not need for a user guide :slight_smile: Or on each page of the user journey identify what can be the questions and have some form of pop-in support. Like when first contact with the admin panel, a pop-in would appear with the 5-6-7 enterprise models and you can clic on your type of enterprise and you have a custom “demo” a bit like when you connect to Slack the first time, the platform shows you things live.

Ok we’ll see that in a few years :wink: Meanwhile I think we could have a pop-in when first connection to admin panel with a choice between 5-6-7 “quick start guides” depending on the type of entreprise you want to set up, as suggested by Theresa.

But that doesn’t prevent us to have an extensive user guide that anyone can refer too, we do also have users who read it, so maybe GitBook as you said could be a good option… can we in GitBook have specific pages for specific local instances? Or for multilingual is it only a translation mode? @pmackay I’m sure you will know that :wink: I guess we can coordinate the same way we do for the code and have one version of the user guide as we have only one master code anyway :wink:

I will ask some users in France what they think about it :wink:

had need to use the user guide again today, to try and find out how to use things I don’t know how to use (which is exciting in itself ;), and couldn’t find info on inventory . . which brought this back to my attention! From a quick scanning through the above it seems like there is strong interest in gitbooks but some outstanding questions about:

  • number of collaborators, potentially overcome if we put in openfoodfoundation which would mean that Admin, Core Developers and Issue Managers (as described here) would all be able to edit it, which seems like it would solve this problem. Trust level probably similar?
  • were there questions about translation management that still need resolving?

I’d be really keen to see this show on the road and think a test setup would be great @pmackay

then if we like it we can work out who/how to actually get it done . .

1 Like

There are alternatives to Gitbook. I looked at two.

Penflip allows unlimited collaborators for free: as long as you make your document public.

I’ve never used this, but read enough of the documentation to see that it actually uses Git as part of its platform:

It seems to be more oriented to creating books than documentation, but I think they use their tool to maintain their helpfiles.

One downside (maybe) - I saw a “contributor” that was actually a spammer. I think this is controllable, but not sure.

A second downside is that - as a hosted service - there’s a risk it disappears if the operators go out of business. Downloading the current file on a frequent basis could control that risk.

The other tool I looked at (briefly) was I didn’t see anything for collaboration, bit it looked like a decent platform to create and structure documentation and it claims to support multiple languages.

It’s open source and available on github. The project looks reasonably active.

For grins, I started a project in Penflip and copied some of the existing documentation into it. The editor seemed slow to me and I don’t think there’s support for video. but the UI looks very similar to the one in gitbook, so it seems like a viable alternative.

To see what I did, go to and enter OFN.

If I read the version control part of the documentation correctly, each person’s version is a separate document and edits to the “main” project are submitted (just like gitbook). So that suggests that users in other languages could create in-language versions and just leave them as they are. (Seems awkward, but it might work).

Let me know if this post was helpful.

Hi all!

I’m Simone and at the moment working with the Australian team for a couple of months, I will probably have some time to work on the user guide. I just had a non-technical, shop point of view, look at gitbook and penflip and below are my quick thoughts.

-Structure: the headings on the left side and the written text on the right side make a very neat and clear overview

  • It can be used within OFN, without going to another website
  • Open to suggestions in a very friendly way “If you can see room for improvement, please feel free to edit this page.”
  • There are ‘sharing on social media’ links embedded: not sure if this is necessary but it could be used in a creative way perhaps?
  • Arrows on every page, so easy to keep scrolling through pages
  • There is a ‘+’ sign that allows people to comment → very usefull! Then we know if things in the guide are not clear
  • You can insert video’s and photos and graphics


  • Looks like it is an extra link. It leads you to a different place.
  • It doesn’t have arrows to keep going through the pages. You have to make an effort yourself to click on other chapters. (more effort = less likely for people to keep reading?)
  • Looks very basic, but perhaps that is the example I saw (the OFN one)
  • The ‘discussion’ and ‘changes’ boxes are always visible when you read the guide, so you can easily click on that and see the latest changes etc.

I really like the gitbook option, and wonder if anyone has an understanding of how we should translate - there seem to be a variety of options to help with machine translation that could help us get over the hump to then refine, but I have not had a chance to delve in and learn more.
We will also have to look at how we manage updates to trickle down for translation to ensure consistency across translations?