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

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 https://github.com/openfoodfoundation. 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 https://help.gitbook.com/github/can-i-host-on-github.html. 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. https://handbook.enspiral.com/) that could live at guide.openfoodnetwork.org. Just a set of web pages to read, only editors would need to know it is hosted on Gitbook/Github.

2 Likes

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. http://alternativeto.net/software/gitbook/?license=free I looked at two.

Penflip allows unlimited collaborators for free: https://www.penflip.com/ 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: https://www.penflip.com/Penflip/help/blob/master/working-offline/WorkingOffline.txt

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 Daux.io. 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 penflip.com/discover 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.

Gitbook
-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

Penflip

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

Yep, we def should understand how translation will work in practice with gitbooks. Are you able to give @simoneluijckx any suggestions / signposts re how to look into this further? (otherwise we’ll figure it out!)

will gather some links and see what I can dig up @serenity
@simoneluijckx let me know where I can help out.

gathering links here:
https://github.com/darkcircle/po4gitbook
https://userbase.kde.org/Lokalize
https://wiki.gnome.org/Apps/Gtranslator

from this it looks like Gitbook is in the lead!

@pmackay do you still have capacity to set up gitbook for us? We’re ready to go!!! @simoneluijckx

@serenity I have not had a chance to dive down the rabbit hole on this yet, just gathering links so we can figure this all out together, but yet to have done the research.

@pmackay do you have any input on the tech aspect for the translation end of things?

ping @sigmundpetersen thoughts on this? Any chance you want to dig in here? :wink:

@MyriamBoure you have already done the bulk of the translation for French as far as I recall, what are your thoughts on how will manage updates for consistency across instances?

From: https://toolchain.gitbook.com/languages.html


GitBook supports building books written in multiple languages. Each language should be a sub-directory following the normal GitBook format, and a file named LANGS.md should be present at the root of the repository with the following format:

# Languages

* [English] (en/)
* [French] (fr/)
* [Español] (es/)

–> This is easy, but would be just in case we have translated the guide by ourselves

Also what you can do is list translated versions with their last time updated, so that people know if a translation is likely to be out-of-date:

  • French (Last update: 07/10/2016)

An example of a GitBook that uses volunteers to translate it : https://python.swaroopch.com/translations.html
"There are many translations of the book available in different human languages, thanks to many tireless volunteers! If you want to help with these translations, please see the list of volunteers and languages below and decide if you want to start a new translation or help in existing translation projects. If you plan to start a new translation, please read the Translation how-to."

–> Is this a way that we can translate the Userguide? By asking volunteers? @Serenity Do you have experience with this?

I think using git would be a great idea.

Trying to understand what ‘Userbase’ is, but this is the only info I can find: "UserBase is a repository for user-centric information regarding any part of a KDE release. It is a wiki, written by volunteers, and editable by any registered user."
Does this mean we have to make a Wiki of the userguide for it to be translated?

And info on the Gtranslator: “Gtranslator is a specialized computer-assisted translation software and po file editor for the internationalization and localization (i18n) of software that uses the gettext system.” So if we could get the userguide transformed to a gettext (via po4gitbook?) this could help us translate it easily?
However, I saw on the website that the Gtranslator is ‘unmaintained’ at the moment.

PS. my knowledge on digital stuff is nihil, so maybe I am interpreting this totally wrong

If it helps, I’ve tested Google Translate for another business (English to Spanish) and it was very good. There were some awkward phrasings here and there, but the meaning was preserved 100%.

It might be laborious to copy and paste the text paragraph by paragraph into Google Translate, but it’s free.

For reference, below are the major ‘wishlist’ features that people want to have in the new user guide platform (based on various comments in this thread). Once we have a play with Gitbooks, it would be good to measure how it performs…

  • Able to translate base content
  • Able to add/remove content for each instance (e.g. Australia may have a section on tax that others don’t need).
  • Have multiple ‘English’ versions (Canada, UK, Aus). But also have one version in multiple languages (Canada = french and english)
  • Searchable
  • Free standing pages that can be linked in a table of contents (rather than in a setup guide). Some navigation features like arrows between pages and menus.
  • User friendly appearance (is it pretty? Can we give it OFN branding?)
  • Aesthetic/formatting things like being able to add photos, links (that update), videos, headings, expando collapso, anchors, buttons.
  • Multiple people able to add suggestions or edit content.
  • Notifications of changes made between instances.
  • Comments and questions from readers.
  • Ability to house the user guide on each local instance and for the users to not need to navigate between languages or instances (E.g. Aus user accidentally ending up in UK guide).
  • Ease of use - being able to get interns to work with the platform without needing prior knowledge.

For reference also, below are all the suggestions made in the thread:

  • Wiki
  • Wordpress plugin
  • Wordpress overhaul - new URL, updated Avada.
  • Discourse
  • PenFlip
  • Daux.io
  • Gitbooks

@simoneluijckx

So dumb question… If I wanted the files for the user guide - either in WP or in plain text, how do I get a copy?

I’ve read through this thread and the preceding enough to know that it’s in WordPress, but how can it be accessed?

PS: I"m willing to fund the copying of the text to Gitbook if I can use an offshore resource.