User guide harmonizations : what could be our new common skeleton?

International Guide Updates
1

Why?

We need a common architecture for our user guides to enable easy maintenance, and especially, now that we decided to evolve toward “language user guides” rather than “instance user guides”. In Canada for instance if French speaking people access a user guide radically different from English speaking people that can be problematic, especially for support teams…

Evolution we did in France

https://ofnuserguidefr.gitbook.io/guide-utilisateur-open-food-network

When we worked on the French user guide we questioned the current architecture of the English user guide and decided to evolve it.

We thought there was missing some “quick start” guide and added it, inspired by something we found on UK website. We thought also that basic vs advanced features was not a relevant distinction, as for some users advanced is basic, depending on their case, and it’s super subjective to tell if a feature is basic or advanced.

So we went for the following approach in France :

1- A quick startup guide : 6 steps to create your shop, that redirects to some pages in the features section used to create a shop as a quick start. [we added that compared to EN user guide]
2- Then 2 “entries”:

  • one per user profile (you are … then check this and this). We listed 8 user profiles and made easy to find yours through one simple table, then detailed them one by one.
    • Producer who don’t want a shop, only supply to other shops or want to be discovered
    • Producer with a shop, sells his products only
    • Producer that resells products from other on top of her products
    • Group of producers with a common shop
    • Distributor who don’t want to sell through the OFN but just be visible
    • Distributor selling through an OFN online shop
    • Farmer market who don’t want to sell through the OFN but just be visible
    • Farmer market who sells through OFN

[we changed the content here but not the structure compared to EN user guide]
Of course there are redundancies, but we don’t care, we help people identify through the table and some concrete examples which user profile correspond to them, and on that user profile page we explain the advantages of OFN, and how to set it up, sending to the relevant feature pages.

  • one per feature. We sorted the feature by some “chronological / domain” use, :
    • Registration and profile creation
    • User profile
    • Products
    • Shop
    • Orders
    • Subscriptions
    • Reports
    • Dashboard
    • Groups

[we removed the basic / advanced distinction and grouped the page per “management domain” following a bit the chronological work to be done]

3- Then we have added a section called “complementary software” with sub-pages per “management domain”, so far we only have “communication” and we have one page on Mailchimp, like how they can use Mailchimp for their coms alongside the OFN.
4- And last, FAQ

Full detailed plan here : https://docs.google.com/document/d/1hG6OTvIieajLODmMlTYKKTgNxtGPqVjHKkrtnWo1wTo/edit?usp=sharing

We already have started to think the French guide as a “language guide” as it is used by Belgium, etc. So I don’t think there is anything “French instance specific” in it, and if we do in the future we would have subpages under the features concerned, or table for instance on payment gateway available, we could specify per country which one are in use, etc. That could be done as well if we end up having only en English version automatically translated.

Feedbacks and way forward

What do you think of it ? If you like that approach we are happy to share with you a detailed table of content of every page so you can see if that seems logical to you, if we are missing something, etc. So we can go toward some consent on a common skeleton we all agree on. How does it sound ?

Else if you prefer to start from another proposal we are of course open to other proposals :slight_smile:

Ping @lin_d_hop @Jen @Kirsten @Rachel @gen.shanahan @NickWeir after the all the thing meeting, and @tschumilas @lauriewayne1 who have been involved in the precedent discussions on the topic.

2

Ok so given my last comment here User Guide as a Living Document - how to keep it current/rich/relevant? I propose to move forward on re-harmonizing and agreed upon content around a “master English user guide version” that would be the only one we would collectively maintain as far as content is concerned, and that we would purely translate in various languages, for now with manual translation (we can use tools like DeepL to help us so pure translations should be quick to do).

I just finished a big review of the French user guide, so if we agree on that path I can first make a detailed table of content of the form the new English master version would take, and when we agree on it, I can duplicate the English Gitbook to prepare a new version that would replace the current one. I’m happy to pair and work in team with other people on it of course, even if I’m conscious doing back translation from French in English might not be the easiest thing for non English speakers :slight_smile: But we have not changed all pages lots of content is still the same so it’s not about translating everything again… more adjustments and compare-reading of formulations, etc.

What do you think all ? @lin_d_hop @Rachel @tschumilas @lauriewayne1 @EmilyRogers @Kirsten …

3

Hi Myriam
I did a bit of brainstorming about the user guide the other day and it is baffling to know where to start to reorganise it.
I suspect people will use it in primarily two different ways:

  1. to set up- these users are likely to go through things page by page chronilogically
  2. to trouble shoot- these users need a guide which is easily searchable
    In terms of removing the basic and advance sections, this seems reasonable at first glance but then they are kind of re-introduced (under different names) if you have a ‘quick start’ section (basics) and everything else. Or is this just my view?
    I think we are all so used to OFN that perhaps the terminology we take fore-granted to describe ‘shops’ , ‘hubs’ etc is not that clear to the user.
    I like the idea of a quick start section for different people/users but could it be much simpler? Maybe only 3 or 4 options rather than 8? maybe a flow chart with a series of questions (do you want to sell through OFN? Do you sell your own produce? Do you sell other people’s produce) which directs the user to the correct quick start rather than a table where we use OFN language/jargon which might not be clear?
    Maybe as well as an FAQ section, a trouble shooting section? There are common errors we come across as support (inventory settings being one) and so it might help the user to feel ‘enabled’ if they can fix their own problems?
    A link to the support forum and support request contact form in the footer of each page might be good so the user can easily get in contact?
4

Oh I shared an idea of synchonization that’s a little more crowdsource-y maybe in the other thread (User Guide as a Living Document - how to keep it current/rich/relevant?). I’m maybe more interested in the process than in the specific structure or content (I do care about it but I don’t have enough experience to have a worthwhile opinion).

I do have to say I always get a little nervous when I see references like “support forum and support request” since I sort of take it to mean “if what you want to understand isn’t in this guide, there is an alternative process for supporting you and when you ask a question you can expect a timely answer” which is only the case where someone(s) who has time and experience is receiving and answering the question" (as much as we would like that, it has never been the case in the US).

Probably more of a meta question or maybe a new thread, but how does a user guide fit in with all the other support options in a given country? is that relationship the same across instances, or is it influenced by each instance’s particular set of resources, cultural preferences, and user demographics?

5

@lauriewayne1
Every instance uses the user guide to:

  • Figure out how OFN works
  • Link users to so that they can figure out OFN as best as possible for themselves.

Real people are very important for growing the community around an instance. Users do not come to OFN for the clunky software. They come because there is a person or people who care about them and help them do things. This is the same in every instance and is possibly the most important aspect of building an community around the instance.

1 Like
6

I could not agree more @lin_d_hop! If a brand is defined as “the promise of an experience”, people who care and help each other do things really is OFN’s brand. Not being able to fulfill that promise has been our proven US method for chasing users away, but that’s a different discussion! :slight_smile:
Clarification about your second bullet - you mean link users to each other so they can help each other figure out OFN, is that correct?

7

@lbwright22 I like your thinking about the two usages of the guide and agree.

In the French view, the “quick start guide” is a super short page (see here) pointing the basic steps to setup and start using OFN, so it gives the logic of how it works : create entreprises first, then link to producers or create some, add products, check you have payment and delivery method, and create an OC, and BOOM you are done. So it is not separating features into basic and advanced, you see ?

Agree with terminology, even if hard for non native English to tell about it, but we had lots of thinking in French about the use of term “hub” for instance, we we are still unclear, sometime we talk hubs, sometime shops, sometime distributor, etc. This require probably user feedback / interviews in every language, would be interesting to know if some of you have already talked about this with users. Maybe ask a user who would be happy to support to read the guide and give feedback ? Against free use for some months :wink:

Having an entry per type of users can indeed be rediscuss, I agree with you, maybe we can simplify yes there is probably a lot of redundancy. In France we do have a table but have tried to adapt the language to really the concrete words people use so they can identify and then are directed to the write profile guide, but happy to discuss and brainstorm if the approach should evolve. The thing is that if we have a international version, this for instance will be tricky as we need to find somehow equivalents to all models in every country, but will be super interesting also to do and useful for sector development products :slight_smile:

We do have a FAQ section in french UG : https://ofnuserguidefr.gitbook.io/guide-utilisateur-open-food-network/faqs

Yes, need a clearer link to support request (again this needs to be thought in international perspective, like a list of local instance with support email contact or redirection to ticketing page for each one).

I’ll propose straight away in Slack to setup a date for a remote coworking session where we can go section by section and build together a shared proposal of common squeleton taking into account all your feedbacks @lbwright22.

8

I did a more detailed plan of what we have in France, could be a basis to then change together in a meeting to go toward some agreed upon skeleton.


@lbwright22

9

@MyriamBoure I like your ideas for the quick start (being really short intro with links to how to do the specific things that people need first off) :slightly_smiling_face:
Still wondering if there is a better way to direct people which avoids the use of words like ‘shop’, ‘hub’, ‘profile’ etc.
Looking forward to talking about it further- added my availability to the doodle poll