Trialling Gitbook for User Guide . . YAY!

International Community
1

Project Overview at PROJ: OFN User Guide to Gitbook

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

We are trying to get the following features working:

We have installed the plugins below. I think they need a bit of fiddling to work out how to actually use them . . I started but have run out of time. Notes below, hopefully @simoneluijckx and @sstead will have more luck!

I think I have set the discussion / comment features etc so that they will work as you need them

image.png1504×614 50.4 KB

We need to do a bit of restructuring to handle language stuff . . but perhaps test this all out first and I can look at that next week

2

NB. Helpful notes if anyone wants to work on custom theming . . I am putting that as ‘next step’ after we’ve confirmed functionality ok

For custom CSS styles, add a CSS file to your book’s repo, and update book.json to tell GitBook where the file lives:

"website": "path/to/file.css"

},

If you want more control over the HTML used in the layout, copy the _layouts folder from the theme you’re currently using, add it to your book’s repo, and then customize as necessary. That might take some additional work.

3

and notes on doing the plugins

eskwayrd [11:48 AM]
@kirsten Installing the plugins is a simple matter of editing your book.json. If a plugin is available at https://plugins.gitbook.com/, you just include its name in the plugins: section of book.json. For example:

    "accordion",
    "collapsible-menu",
    "videoclips",
    ...
  ],
4

Before starting on the transfer from userguide to Gitbook I have some questions and words I don’t understand. Maybe it’s the language, more probably it’s the tech terms :wink: We can make a ‘glossary’ perhaps, as @Kirsten suggested! If more people are unfamiliair with them.

Words / abbr

  • anchor links:
  • OFN CC:
  • Repo:

Questions

  • Are we focussing on copying the userguide or on updating and adapting it before transferring it to Gitbook?
  • When would the userguide be ‘smart and collaborative’ to us? Or to users? (So, what do we need to change to make it smart and collaborative?)
  • Do we have specific feedback on the content and/or structure of the userguide from users / OFN team to take into account?
  • Gitbook is synched with Github, how can we make changes by using Github? (or is this not applicable to me?)
  • What do you prefer us to use when making changes, Gitbook or Github?
5

Think this refers to internal linking inside a Gitbook

OFN Core Commons funding, see

We fund OFN projects and processed collaboratively through the Co-budget tool :slight_smile:

Repository; like OFN main github repo or OFN User guide repo

1 Like
7

My responses to Questions

1. Are we focussing on copying the userguide or on updating and adapting it before transferring it to Gitbook?
The current version is already transferred to gitbook (or version from a month or two ago when @jveilleux got someone to do it). I’m open to @sstead’s view on how to do this . . but for my 2c I’ve started using the gitbook one already because the searchable-ness makes it easy for me to find things when I can’t find them in the wordpress one. So I suspect we should be focusing on improving, updating and adapting the gitbook version

2. When would the userguide be ‘smart and collaborative’ to us? Or to users? (So, what do we need to change to make it smart and collaborative?
Not sure … others probably have a better handle on this. I think the version control, forking and other features of Gitbook will go a long way to delivering this

3. Do we have specific feedback on the content and/or structure of the userguide from users / OFN team to take into account?

  • If you can get accordion / expand-collapse menus working well, I think a lot more sub-pages will make sense. Gitbook allows easy clicking through to the next page to flow sequentially, but when you search it shows you the page titles and first para . . so having pages with quite specific titles will make it easier for people to go exactly to the one they want
  • I am not sure how the linking will work, but hopeful that this system will make it easier to refer to the same page / content from multiple places. So the structure with ‘type-led’ instructions e.g. as a farmers’ market can co-exist nicely with set-up guides etc

4. Gitbook is synched with Github, how can we make changes by using Github? (or is this not applicable to me?)- What do you prefer us to use when making changes, Gitbook or Github?

  • I think you will find Gitbook easier to get going, but no problem if you become familiar with github and prefer to do it there - might actually run quicker. There may be some syntax considerations, but you would be able to work that out easily if there are
8

I guess maybe something like this guide makes a good starting point on how you can work with the markdown files (gitbook pages) on desktop/offline. Team this up with the github repo and you have your editing alternative to in-browser editing at gitbook.com

9

Tips & Tricks

Collapseble chapters

  1. Right click on Chapter in left menu
  2. Add ‘new article’
  3. When adding new content: copy paste it in there / start writing. No further steps needed.
  4. When adding an existing paragraph as a subchapter, take step 1 and 2.
  5. Fill in a random new name for the article
  6. Click ‘add’
  7. Now right click on this article and click ‘Edit pointer’: you can enter a file or url name
  8. Fill in the file name of the existing paragraph you want to add
  9. Choose your paragraph and click ‘add’.
  10. You now have 2 identical paragraphs in Gitbook, delete the one who’s not in the right place.

Internal linking (anchor links)

Here’s the guide on how to do it: https://seadude.gitbooks.io/learn-gitbook/content/chapter1/internal.html but you still need to know these things:

  • Linking to (sub)chapters
    This is the example code:
    [link text](../<chapter>/<article>.md)
    To easily find the text fitting here: <chapter>/<article>.md right click on the chapter you want to link to and click ‘Edit Pointer’. Here you find the text.
    image.png746×531 24.9 KB
  • Youtube plugin:

Used the embedded code and copied straight into the Gitbook file. This video told me to do so →

So did NOT use this format:
{% youtube src=“https://www.youtube.com/watch?v=9bZkp7q19f0” %}{% endyoutube %}

But this one:
< iframe width=“669” height=“376” src=“https://www.youtube.com/embed/eA3IcMUnU14” frameborder=“0” allowfullscreen>

  • Viewing and working with the code

Enable ‘edit markdown’ to view and work in the code. Go to the right bottom question mark icon for this. This way you can also easily make changes.

  • Copy and paste

DON’T use the ‘ctrl+c and ctrl+v’ keys to copy text from userguide to Gitbook. Somehow makes it very hard to edit the text → the pointer keeps jumping away and reacts very weird on changing text style.
DO use the copy paste with your right click.

Also saw this tip:
“The paste seems to go through if you paste to a blank line with a blank line on either side. The paste seemed to fail most often in cases where I was pasting into markdown URLs. If I framed the URL with brackets and parentheses first, I wouldn’t be able to paste inside of them. Making a few extra blank lines so I could paste, pasting, and then deleting the extra lines to make it look as intended seemed to do the trick.”

  • Grammarly

I was using Grammarly for the spellcheck, but this made editing on the page impossible. Kept changing my pointer and selecting words I didn’t want to. When I disabled the Grammarly extension, everything worked normal again.

10

Last update Wednesday 4 Oct
Changes made by me:

Content of ‘Getting Started’ set-up

  • Chunking of content → into steps
  • Made content brief and short
  • Numbered steps
  • Begin with action verbs
  • ‘Dashboard page’ left out of the ‘getting started’ set-up → still in the userguide, but another position

Questions for now @sstead

? What is the difference between a ‘producer hub’ or a ‘hub shop
? What is the difference between ‘package, account, profile’ → seems confusing when explaining first set-up steps
? What is the difference between ‘change package’ or go to ‘Enterprise’ and change things? → change package section
? Your profile page (step 4): right now this is an overview of all the sections in the right bar of your profile page. I think we can use this as a special chapter ‘all the sections explained’, but I don’t think they have to go through all the info to finish their account and be visible and get started.
Can we recreate this page to the necessary steps only?

  • Added:
    Setup guide:
    → ‘Getting started’ section (step 1 till 4)
    → ‘amount of time’ and ‘what’s needed’ at beginning of each step
    Cover page
    Frequently Used Terms
    Some extra FAQs
    Embedded shopfront page
  • Collapsable + subchapters:
  • Case studies
  • Advanced Features

  • FAQs

  • Added some FAQs

  • Made FAQs chapter collapsable: (can someone check if I copied them right?)
    → Right click on Chapter in left menu

    image.png1366×768 193 KB

    → Need to add ‘new article’ (you can not move an existing chapter as a daughter under a mother chapter)
    → ‘Right click copy paste’ the markdown text from the existing chapter to the new article
    → Delete the old chapter

  • Accordion: Expandable textblocks added
    → use this code:

%accordion%Some title here%accordion%

Any content here

%/accordion%

NB: for the title, delete the headingstyle, use plain text only
It doesn’t work if the #### are used.
Example gone wrong

image.png1070×298 32.6 KB

11

Remarks

Confirmation emails from OFN

  • ‘Old’ userguide link is in ‘Welcome on OFN’ and ‘confirm email address’ email. Change when GitBook is launched.
    image.png704×364 20 KB

Set-up Guide chapter: the content

  • Step 1: create an account
    –> here you already have to choose if you’re a producer or not. I think we should mention this, since we are making a distinction in the whole userguide between those two.
    –> profile only is also an option. All the terms confuse me a bit, not knowing what to choose. Should we just not mention the ‘profile only’ option, since it is explained in step 2?
    –> what is the difference between ‘account’ and ‘profile’? They are used intertwined, but mean different things: account can be profile / shop. Profile is a type of account: ‘profile only account’. I think?

  • Step 2: Profile types
    –> splitting it up into 2 pages here?
    –> should we put the ‘change account type’ in another chapter? To prevent overload on info.
    –> is your enterprise not visible of you don’t follow step 2?

Discussion feature

  • When someone comments / starts a discussion, I don’t receive an email notification of this even though I am a collaborator of the book.
    –> Need to check the discussion regularly ourselves
    –> Who’s responsible for this?

  • The discussion ‘+’ box does not work with text in a collapsible (accordion) menu

    image.png785×342 18.8 KB

Language style

  • Use ‘Open Food Network’ instead of OFN --> after comment of Jen: “As part of developing key messages etc at the moment I’ve been doing some thinking about ‘OFN’. And I think we need to stop saying OFN and start always saying Open Food Network when we’re talking about ourselves to customers, in social media, in talks, etc. OFN doesn’t mean or say much, whereas Open Food Network has values and our core business embodied in it.”
12

Which pages in the Producer/Hub setup guides differ dramatically? Could we remove this duplicating structure?
It would be best not to have duplicate pages, but maybe it’s worth the effort for the additional useability?

  1. Create an account - SAME (have created generic page https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/content/create-an-account.html)
  2. Profile types - Have different screenshots for producer/hub packages. (have created generic page https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/content/hub-profile-types.html)
  3. The Dashboard - This page is pretty redundant. It just has screenshots of the dashboard, which differ depending on producer/hub and profile/shop. (Have created generic page https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/content/the-dashboard.html)
  4. Your Profile - many sections are the same for producers and hubs (Primary details, users, address, contact, social, about, business details, images), and then the there are some fields that only apply to certain types of users (properties, inventory settings, shipping/payment/enterprise fees, tag rules, shop preferences) I think a lot of these sections could/already have their own pages though. (I’ve made one generic page (not hub/producer specific).
  5. Connect with your supplying producers - HUBS ONLY
    Products- There’s producer instructions, and the hub version has additional instructions regarding whether the hub user owns the producer or not.
  6. Payment methods - SAME - we may want individual pages for each payment method? Or not. Or Collapso Expando. (I’ve made one payment method page, with expando collapso- we can always break this up).
  7. Shipping methods - SAME
  8. Enterprise fees - is pretty much the SAME, just that producers are told ‘you probably don’t need these if only selling OWN’.
  9. Order Cycles - the producer OC page is quite a lot simpler, so better to keep these separate.
  10. View Orders - SAME
  11. Reports - SAME - we could turn this into a single report page - with different cases/scenarios which then direct to individuals pages for each report. (There’s just one report page in gitbooks)
  12. Advanced Features - SAME
13

? What is the difference between a ‘producer hub’ or a ‘hub shop
A producer hub, is a producer who is selling their own produce, and also aggregating and selling other producer’s produce. So they are both a producer and a hub. A hub shop doesn’t produce any of their own products.
? What is the difference between ‘package, account, profile’ --> seems confusing when explaining first set-up steps
Package = There are 5 packages. For producers = profile only, producer shop, producer hub. For hubs= profile only, and hub shop. Sometimes each package will have a differenent fee structure.
Account = your email login
Profile = your enterprise’s profile
I can see how this is confusing! Open to alternative ways to phrase these.
? What is the difference between ‘change package’ or go to ‘Enterprise’ and change things? --> change package section
The package page is replicated on the Enterprise page, but if you have >1 enterprise you don’t see change package. They just give an explanation of the packages, what they’re used for, and the fees attached. See below

image.png923×373 25 KB

? Your profile page (step 4): right now this is an overview of all the sections in the right bar of your profile page. I think we can use this as a special chapter ‘all the sections explained’, but I don’t think they have to go through all the info to finish their account and be visible and get started.
Can we recreate this page to the necessary steps only?
Yes, that’s true. Not all of those sections are essential to get up and running, so some sections could be covered later, or on a different page. It was a constraint of the Wordpress navigation that you had to put it in a likely spot, even though it’s definitely overwhelming for a first time person setting up.

14

Comments on Gitbook features

  • Menu hierarchy- expand and collapse
    @Kirsten this is what you mentioned:
    Yes, works but it does not always collapse:
    Not collapsing when:

Does collapse when:

Subchapters are working:

image.png1163×375 21.2 KB

  • Expando Collapso within chapters
    Yes, works but with the accordion plug-in. I could not get the other plug-ins to work.
    image.png922×509 19.9 KB

image.png783×537 24.5 KB

  • Custom themeing
    Not looked in yet

  • Embedded videos
    Yes, works but not with the plug-in code. You use the embedded code of the video and copy it into gitbook.

  • Multilingual
    Will be looked in soon?

  • discussion / comment feature
    Yes, works but not too convenient.
    To comment, you have to hover over the text. Then a + box appears, but it doesn’t say this is for commenting. You have to understand that yourself apparently.

image.png860×343 14.4 KB

  1. When clicking, you have to sign in first.
    image.png785×246 8.57 KB

We don’t receive an email notification of someone commenting, not even if you’re a collaborator of the book.
It does show in the discussion box on the masterpage of the Gitbook userguide.
We will have to check regularly ourselves if there are new comments.
You do get an email notification when someone comments on a discussion/comment you started yourself.

image.png1015×487 37 KB

  • Search tool
    Yes, works, it shows menu header, chapter header and accompanying text. You can play with the names of the paragraph headers and the menu headers, to make the search outcome more efficient (e.g. not using same header titles)
    image.png1214×542 39.6 KB
15

Following this question:
Q: Your profile page (step 4): right now this is an overview of all the sections in the right bar of your profile page. Can we recreate this page to the necessary steps only?
A: Yes, that’s true. Not all of those sections are essential to get up and running, so some sections could be covered later, or on a different page.

This is the overview of the ‘your profile page’ paragraph:
Same content for producers and hubs

  1. Primary details
    –> Name, visible in search, permalink, link to shopfront
  2. Users
    –> Owner, manager
  3. address
  4. contact
  5. social
  6. about
  7. business details (is this not only applicable when you have a shop?)
  8. Images
    Online Shop only
  9. Properties (producer only)
  10. Inventory settings
  11. Shipping methods, payment methods
  12. Tag rules
  13. Shop preferences

Different for producer/hub

  1. Primary details:
    –> Primary producer: different content
  2. Users
    –> Notifications (hub only?)
  3. Properties (producer only?)
  4. Enterprise fees: for profile only producers, who supply hub

Idea for Set-Up page
Do not add step 4 ‘Your Profile’ to the ‘getting started’ steps. It contains no action steps and so much info you don’t need to read to just set up a profile.
Instead, we could make a step 4 containing only the necessary finishing steps to create your profile.
→ perhaps show how to view your profile (‘as a customer’) and then refer to the edit page if they are not happy with things.
Q: Do you actually still have to take steps to fulfil the process of creating a profile?
Q: If so, do you know the necessary steps people have to do to fully setup their profile (only)?

16

amazing work @simoneluijckx and @sstead - this is going to be awesome!!

I am having lot of trouble with the expando/collapso side menus though - they seem really weird / not working to me? could they just be jumbling all the sub-menus in a big pile at the bottom?

image.png536×1050 49.8 KB

17

once i actually click on the title i think the sub-headings appear, but otherwise they just open and close with no sub-headings?

image.png620×694 30 KB

18

@Kirsten yes, true! I noticed it as well. In the ‘Comments on Gitbook features’ I’ve explained in images how it works. It is annoying though.
I made a chapter in the userguide on ‘how to use this guide’ and maybe we should add a little paragraph about some handy ‘tech’ things to know when using it, like this one, to click on chapters and not on the arrows.

1 Like
19

2 - Profile types - Have different screenshots for producer/hub packages. (have created generic page https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/content/hub-profile-types.html1)

SL --> this generic page now is structured as the first step for ‘setting up an online shop’. But it doesn’t match with with this intro: https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/content/continue-create-online-shop.html --> "The following steps are relevant to users who wish to establish an online shop. If you wish to have an online profile only, you don’t have to follow these steps."
Q: do we need this page?

4 - Your Profile - many sections are the same for producers and hubs and then there are some fields that only apply to certain types of users. (I’ve made one generic page (not hub/producer specific).

SL --> the content of this page is connected to step 3 ‘personalize your profile’ https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/content/personalize-profile.html. Are there any steps or edits you have to do to complete creating your profile? So: if you wouldn’t edit or personalize anything via the dashboard, would that still mean you have a visible, complete and working online profile?
If you would need to edit some things, what are the necessary ones? This way we can make a distinction between steps you must take and steps you can take, directing them to the ‘edit page’ which shows the dashboard descriptions.

ss_ I’ve tried to make this a little clearer. To get just a profile, just just need to register, confirm your email and select a package. But it’s good to also introduce profile only users to where they can update/manage their profile.

Online shop set-up (for prod + hubs)

SL --> Made this one page for producers and hubs via: pointing out what function they are seeking for and which steps belong to this function. https://ofn-user-guide.gitbooks.io/ofn-user-guide-master/continue-create-online-shop.html
Visually it isn’t looking very neat yet, but this is maybe an idea on how to structure these set-up steps?

6 - Payment methods - SAME - we may want individual pages for each payment method? Or not. Or Collapso Expando. (I’ve made one payment method page, with expando collapso- we can always break this up).

SL --> Added set-up steps to this page. Tried internal linking within the chapter, but it is strangely not working. Used this method:
Relative Internal Link to a heading in the SAME article:
Syntax:
[heading](#test)
Format:
[link text](#<heading-name>)