@jveilleux email me (hello@openfoodnetwork.org) with your email and I can give you a login for the global wordpress site (where the user guide is housed).
hey @jveilleux could you maybe explain a bit why you need access / the files?
Your offer may be of interest, once @simoneluijckx (who I think is working on this) is not with us, but I think is something we should probably discuss more broadly. I am not that enamoured in someone who is not familiar with the system (or interested in learning) doing it, as I see it as a great opportunity to check, update, reorganise and keep getting it better. A simple copy and paste potentially wonāt take advantage of the new structure and system? Do you have someone particular in mind to do this and how much would it cost?
I keep failing to make myself clear. sorry about that.
For my part, I need a userās guide that is customized to our business model and that focuses on the functionality we want users to understand. And I need to delete references and links to OFN that will confuse our users. I only want access to speed the process of copying the text to a Gitbook account where weād make the changes that we want.
My offer was not to take over the care and feeding of the user guide, but only to provide the raw labor to get the new system started. I was assuming that we (OFN) were moving to GitBook (was I wrong?) and that someone would need to do the drudgery of copying/pasting the existing content into the Gitbook structure (I tried this myself a bit to see what it would be like).
To preserve the hyper-linked structure of the current user guide, each of the pages needs to be copied to an āarticleā or āchapterā, then linked within so each page is properly connected. Itās not rocket science, but it would be tedious. Iād find someone on Freelancer.com to do this for less than $100 - maybe much less. Then Iād turn the account over to OFN so you all can maintain it and make it accessible to others to create their translated versions.
With regard to this:
I can only say that having someone do the grunt work might free up time to do just what you suggest.
Unless youāve got someone working on the conversion to GitBooks right now, I donāt see much of a downside for OFN. Even if you decide later not to use git, it just means that there will be a version sitting in gitbooks doing nothing much.
If you have no objection, Iām going to respond to @sstead with my email as she suggested. But Iāll wait for you to respond before logging in. I want you to feel comfortable with what Iām doing. Let me know if youāre still wary and why and Iāll try to address any specific concerns.
BTW - my plan is to copy the WP site files to another WP site so thereās no risk of having a freelancer editing your files by mistake.
Thanks.
Jim
@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 
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.
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)?
- @jveilleux: yes
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)?
- @jveilleux: yes, as far as I can see.
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!!
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