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

@pmackay you mentioned you may be able to setup Gitbooks for us? Do you still have time for this? Itā€™s ok if not, just let me know. Our plan moving forward is to setup a mockup of how the guide may function within gitbooks (with a new structure). Then weā€™ll ask the global community to assess whether it meets their translation/instance customisation requirements. If all good, weā€™ll more the guide over to Gitbooks fully. Cheers.

@sstead Iā€™m away for this week, can aim to start something next weekend if that works. Unless @jveilleux solves it first :slight_smile:

Hereā€™s my plan for putting this mockup together, for comments, in case Iā€™m wrong.

I would use a personal gitbooks account (seems like you can transfer the account to another account, which is my plan to transfer to OFN account).

Each page would be either an article or a chapter, with the hyperlinks re-set to point to the appropriate page within.

I donā€™t see support for video, so the video on the home page (are there more?) would be changed to a link, maybe with a button (will need a test).

I donā€™t see much else that needs to be done. Once I have it set up, Iā€™d transfer or make a copy to transfer to whatever account you had set up.

Let me know if you have other requirements.

Thanks

Errata: Turns out that the Expand/contract functionality thatā€™s in WP doesnā€™t seem to be available in the gitbook editor - that I can see, anyway. So Iā€™m just going to display the answers to the FAQs under the questions, for now, anyway.

ok thanks @jveilleux, that seems ok. I set up an account yesterday and am just playing around with connecting it directly to the Open Food Foundation github organisation. does anyone know if that would force similar permissions per user (we DONā€™T want ability to edit the gitbook to be tied to write access on the code repositories)

Jim - I think if you can hold off another day, then @sstead and @simoneluijckx are going to look at it tomorrow (wednesday aus time) and suggest the best way to migrate content based on what they want to do with it at the other end. I will also have worked out if it makes a difference where we put it, just in case it does and the work can be done into the right place first time around.

I will have some time to look at this properly tomorrow too

Iā€™m not very good at waiting, so Iā€™ve already started the process of creating a gitbook based on the existing website. You can see the current version (still needs work) here at https://jveilleux.gitbooks.io/user-guide/. Iā€™ve hired a guy for $90US to copy/paste and change the links as Iā€™ve described earlier.

Gitbook, while useful, has some limitations, at least from my perspective (may be easily solvable).

One of them is that some of the links in the existing WP site go to the middle of a page (e.g. https://openfoodnetwork.org/user-guide/hubs-set-up-guide/create-or-connect-with-supplying-producers/#supplyingproducer).

I donā€™t see a way to do that in Gitbook (but someone else might).

Anyway, you are welcome to have a copy of this, if itā€™s helpful. I havenā€™t figured out how to do that, but I donā€™t think itā€™s difficult. You may want to wait for a day as my freelancer working on this is likely to put a few more hours in tomorrow.

@sstead @simoneluijckx

Sorry to be so impatient. On a personal level, I have serious ADHD issues.

PS: I found another guy willing to do this for $15US but he was moving too slowly and was difficult to deal with, but heā€™s actually made some good progress as well. https://jveilleux.gitbooks.io/ofn-faq/ Heā€™s in the Palestinian Territory and has some impressive technical skills, but itā€™s been a challenge getting him to understand what I wanted.

Seems there are functioning examples of internal linking here https://seadude.gitbooks.io/learn-gitbook/content/chapter1/internal.html

1 Like

Thanks. I get it now.

Thanks @jveilleux , your copy and pasted Gitbook version of the existing guide gives a great representation of how we could migrate to Gitbooks.

From what I can see, Gitbooks would allow us to create a decent user guide, in terms of structure, navigation and aesthetics. Before we start using Gitbooks as the primary user guide, we still need to answer the remaining questions about having different versions of the guide, how they will link to one another, and how translations will work.

The google doc below lists all of the desired functionality that people have asked for, Iā€™ve commented on the functionality that Iā€™m able to see and test, but I need a dev/multilingual person to explore whether Gitbooks will work across instances. Can we have a master version, and other instance versions branching off. Will it save us time in updating and translating?

It seems like @jveilleux has several actions underway to migrate, so I wont start on this as it looks like it would overlap.

To be clear, Iā€™ve probably gone as far as Iā€™m going to - at least for now - on the Gitbook conversion.

My objective was to create a version from which I could fork a version to the business model my company is going to use for our version of the OFN software. While weā€™ll learn some more things about the functionality of Gitbook from creating our version, Iā€™m not a developer, so I canā€™t speak to the whole list of functionality .

Below Iā€™ve copied your questions in the functionality doc, deleted the answered ones and added my ā€œanswersā€. Note that I havenā€™t tested how well much of this works yet. Iā€™m just replying based on what Iā€™ve seen and read. And Iā€™m learning both github and gitbook as Iā€™m going along.

I added @Kirsten as a collaborator to my gitbook repository on github (OFN Sandbox). Will be glad to do the same for anyone else who asks.

Thanks.


Translating and creating instance versions
Can we translate the ā€˜masterā€™ user guide into different languages?

Yes- but we need someone to play with this and check that we can have French (France) and French (Canada) versions. How friendly is the translation process? Is the translator notified if the master version is updated?

  • @jveilleux: I donā€™t see any translation capability in gitbook. I think you will need to do this in another application and just use gitbook as the repository.

Can we have multiple ā€˜Englishā€™ versions (Canada, UK, Aus). But also have one version in multiple languages (Canada = french and english)?

Can each instance have their own version of the guide, so they can add/remove specific content (e.g. Australia may have a section on tax that others donā€™t need)?

How is a new ā€˜instanceā€™ of the guide created? What is required (dev time, hosting etc)?

  • @jveilleux: I believe you can put the book itself on github and manage versions this way. Then, each of the individual countries can fork the book and work with their version. Iā€™ve created a couple of different forks although Iā€™ve yet to actually make any text changes.

Can we house the user guides on each local instance? Can we prevent the visitors from needing to navigate between languages or instances (E.g. Aus user accidentally ending up in UK guide, or French Canadian ending up in the French guide?)

  • @jveilleux: this is simple. Just put the hyperlink for the appropriate gitbook on the appropriate OFN instance. Note as well, that gitbook lets you output to a PDF and other formats, so youā€™re not limited to gitbook as your publishing medium.

?
Managing content and revisions
Can we have multiple people with permission to edit content of the ā€˜master guideā€™? Is there a cost per user? Can users have limited permission/roles?

  • @jveilleux: I think the way to work around the cost issue may be to use github to manage the versions and gitbook just for the editing and hosting.

Can we receive comments and questions from visitors to the guide?

  • @jveilleux : Iā€™ve specifically seen blog functionality that seems to invite comments.

Ease of use - being able to get interns to work with the platform without needing prior knowledge.
My first impression is that Gitbooks seems to require more developer input/knowledge (especially around plugins and any config beyond the default). Once itā€™s all setup however it may be quite straightforward to add/edit text.

  • @jveilleux: Editing the text is pretty straighforward. Yes, you do need some coding ability for going beyond the editor, although using some of the plugins makes this simple as well.

Someone mentioned you could ā€˜versionā€™ the user guide, so that an instance could upload the guide that reflects the current version of OFN they are operating?
-@jveilleux: What Iā€™ve seen so far is that you can create version in github - rather than gitbook - and then sync to the github branch of your choice. At least thatā€™s my interpretation of what Iā€™ve seen.

Anchors links are for linking half way down a page. Is there a plugin for this? Potentially this?
-@jveilleux: Someone in this thread found examples of how to do this.

  • @jveilleux: I can see links attached to the copied graphics, so Iā€™m sure you can create buttons with links.
1 Like

@Kirsten hereā€™s my take on what needs to happenā€¦

  • Someone needs to setup instance replicate versions of either our test Gitbook, or of @jveilleuxā€™s gitbook. Jimā€™s versions would be better as it has more content to play with, if youā€™re ok with this @jveilleux? This will be the central versions that others branch off of. I canā€™t see how to do this without getting into technical Github territory and I donā€™t have the skills/tech vocab to navigate this. @Kirsten you might be able to do this, or nominate someone who could.
  • if itā€™s possible to take a copy of Jimā€™s gitbook, and then use the copy as the central book that others branch from, that would be ideal, so we donā€™t impact Jim?
  • We need a dev to install some plugins, in order of priority: multilingual (critical)ā€¦ and nice to have ā€¦expanding/collapsing menu, custom themeing and videos.

  • Then instance representatives who will be the ones working with the new user guide platform (@CynthiaReynolds , @MyriamBoure @tschumilas , @mags) need to play with this setup and make sure theyā€™re happy with it. Does the translation plugin work well? Which wishlist items are delivered? Which are not?

  • Once weā€™ve done this weā€™ll know for sure if Gitbook is the desired new platfrom. If so, we can then restructure the user guide in Gitbook.

You are welcome to take a copy. I think Iā€™ve got it cloned in enough places to avoid anyone disturbing what weā€™ve done so far (although, like you, @sstead, Iā€™m not expert in the world of Git.)

Good luck and have fun with it and let me know if I can help in any other way.

1 Like

hi @jveilleux - just trying to get this sorted out and I think I need a couple of additional links or actions from you

I can see your gitbook as a collaborator here - https://www.gitbook.com/book/jveilleux/user-guide/details, but I cannot see anyway within gitbook to copy or clone it.

So I went looking for it on github, as I can then fork it from there to make the base of the general one. I have found you here and a repository called OFNGitbook here but it seems to be empty except for a readme. Could you please send me the github repository for the user-guide as seen at the above link?

I have created a new github organisation called OFNUserGuide so that we can keep everything together without cluttering up the code repo, and control permissions exactly how we want them for this without giving people write access to code. So as soon as I have the correct github link from Jim I can fork into this organisation and we are away!!

Thanks!!

It looks like it is located here https://github.com/jveilleux/FarmFreshWeb

Thanks @woakes070048 - that does look more likely but it seems to have already had some changes to refer to farmfreshweb, whereas the one I can see on gitbooks is referring to OFN. I didnā€™t want to copy one where content had perhaps already been deleted / amended.

Hi @Kirsten

I think you want this one: https://jveilleux.gitbooks.io/user-guide/content/

But if I am reading it correctly, itā€™s easier to make a copy from github, rather than gitbook.

In which case, make your copy from this one: https://github.com/jveilleux/sandbox

You wonā€™t find any edits relative to FarmFreshWeb there.

I tried to send you an invitation as a collaborator, although Iā€™m not sure if thatā€™s necessary, but if so, hereā€™s the link:
https://github.com/jveilleux/sandbox/invitations

I also have another version using the FAQ theme, but Iā€™m not sure if thatā€™s helpful. But if you want it, let me know.

Iā€™m still learning this git stuff. @woakes070048 probably understands it much better than I do.

hi people

I have revisited this . . where I got to was problems integrating the github organisation with the gitbook organisation, which we need so that we can
a) use github for permissions and version control, forking etc AND
b) use gitbook for editing said versions / branches

The issues I am having are documented here - https://docs.google.com/document/d/1UsZ7-Cmj0T-eimUlsSDuEiJNr7Yx-YbnL-T3E5RIOgI/edit?usp=sharing

and I have contacted gitbooks to see if they can help me. Sorry for the delay

@Kirsten did you hear back from Gitbooks? Would be great to get Simone stuck into this while sheā€™s available.

ok, so gitbooks are now officially ignoring me. so it looks like weā€™re not getting any help. I am revisiting this today and taking a 2-pronged approach. I am going to try and rig something up so that we can work in a non-optimal way outside of the organisation set-up AND i am going to entice them by asking if anyone can do some paid work installing those modules we want, which might get them to engage and sort out the other problem, if weā€™re lucky. Will post back here how we go

OK people . . so major progress today :slight_smile:

I eventually worked out the problem (stupid obscure security setting in github preventing the sync), and now have everything talking nicely together and setup.

A lovely person on Gitbook slack has given detailed instructions for the supposedly extremely simple process of installing the plugins and Iā€™m going to have a go at that . . weā€™ll see what happens

I am not 100% clear on the user permission syncing, so have invited both @sstead and @simoneluijckx to gitbook (as owners so you can invite others) but need to then check back how this syncs with github, so we can hopeuflly use github to get around the five person limit.

Have created project management page to keep it all together and closing this thread to create new one for this next stage.
Project Management page