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

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

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 @nick after the all the thing meeting, and @tschumilas @lauriewayne1 who have been involved in the precedent discussions on the topic.