User guide : a view on the new master version (English) + next steps

Tags: #<Tag:0x00007fda64035bd8>

After some working sessions with our little team @lbwright22, @lauriewayne1 and @EmilyRogers, here is a summary of where we are at in overhauling our user guide.

Reminder of the process iteration 1

As a reminder, the strategy iteration 1 we agreed (by lazy consent) to implement is:

  • We rework on the English user guide together to reach an agreed upon version. This version is in English but cover all instances specificities, it could be used on the French instance by an English spealing user in France for instance.
  • We purely translate this master version in other languages, whatever language we want.
  • When someone wants to modify something, we first modify the English version, then notify in the #userguide channel for other language versions to be updated, and if discussions need to happen, enable them.
  • If we see something should be added / modified in the user guide but have no time, we add it on Airtable all the things pipe for this to be picked up.
  • Update of user guide at release time has not yet been confirmed, proposal was to have a “product lead” for each release as there is a tech lead, in charge if checking for the release if implies modifications on the user guide or not before the release is done (@Rachel reminder to include that in the next discussions you have on the topic)

The skeleton of the new English guide

It is still in draft mode in Gitbook, we will finish the overhaul before merging and publishing the new overhauled version.
This User Guide v2 has the given menu entries:

  • Welcome page: first info is link to other language versions, then a quick overview (text and video), and a “how to use that guide” section
  • Local OFN organisations and contacts : as we only have one version translated in many language, for any question / feedback, the visitor needs to know who they can contact. We explain on that page all the local OFN plateform providers and link to their general website AND plateforme entry, and specify in which language those local platforms are available. We also mention that those local providers offer other services like trainings, consulting, incubation programs, etc. (to link with secto dev offers)
  • Quick setup guides: This section is designed for visitors who want help in setting up from scratch on OFN. They are guided through questions toward the “type of profile” they need to choose on OFN, and can see examples of type of hubs the choose each type of profile. For each type (Profile only, producer shop, multi-producers shop) they can access a quick setup page with a visual 5-6 steps guidance and links to the relevant features pages to quickly setup and start using OFN.

Remains to be done here: @lbwright22 rework on a page with a flowchart leading to types of profiles + a “type of hubs” table connecting a typology of users with the type of profile they would need. She also rework on the 3 quick setup guides (for each type of profile), adapting the visual design support.

  • Features: in this section, we go through each feature description in a chronological way of use of OFN + cascading complexity logic.
    Register and create an enterprise account > enterprise profile > products > shopfront > orders > subscriptions > reports > dashboard > groups.
    In each of those “domain” we go from the first and simpler setup to the more complex and specific ones.

Remains to be done here: @MyriamBoure has done the reshuffling of pages, and started to retranslate from French to English all the re-writting work that has been done on the French version. But there is still quite a lot to do. @EmilyRogers will take over, handover call planned Wed. 16th morning.

  • Complementary tools / software: this is basically an “integrations” section, but we didn’t use the work “integration” as our visitors are not tech savy and might not understand. This idea of this section is to describe, on a “product” side (NO TECH), what other software you can integrate the OFN to meet some complementary needs the OFN don’t cover. We organise that section by “job domain” (communication (need to add how to interact OFn with Mailchimp here for instance, in French user guide but not yet in English one) / finances (we put here in a sub section “external payment systems” the page specific to Australia about ABA payments, we need to introduce it of course in the new international scope of the guide) / accounting and invoicing packages (we can add here info on how you can use OFN hand in hand with Quickbooks for instance).
    On lots of software website you have an “integrations” menu that explain you what you can integrate the software with, to do what, etc. Not on tech side but really feature side. This is the idea of this section. We can redirect then to tech documentation if/when it’s needed to implement those integrations.

Remains to be done: feed that section with content. I think @lin_d_hop you would be great to start feeding a bit that section. Maybe @Kirsten and @Rachel as well, the three of you have done some integrations so you might be able to describe on “feature” side what are the current possible integrations, what they enable to do.

  • Hub management tips: THIS SECTION WILL DISAPPEAR AS SOON AS WE HAVE A SPACE TO ACCESS SECTOR DEV RESOURCES. There are some pages in the current English user guide on facebook tips, social media tips, etc. We want this out of the user guide, in a “sector dev resource” section. But for now in a transition phase we propose to keep it here until the sector dev resource space is ready to move those resources there.
  • Trouble shooting: FAQ section, can be fed with most common questions received by support people in all instances
  • Feedbacks: guidance on how to report feedback on this user guide

This was my “handover post” for this task, I’m taking a step back from tomorrow on this. Depending on how things go in the coming weeks I might still be around, but the team has organized as if I would disappear starting tomorrow :slight_smile: So dear folks, just do as if I was not here anymore for some months! @lbwright22 and @lauriewayne1 are taking the lead to organize the next call, after each call, alongwith @EmilyRogers, so the work can keep on moving fast until the team is able to deliver a first version of the user guide v.2.0.

WARNING : we have worked and will keep on working collaboratively on a single DRAFT version in Gitbook. So please be careful while we are in that process with any update of the user guide. If you need a quick modification open a new draft and merge this new draft, and leave our big v2 draft safe until we are ready to merge it :slight_smile:

notes on hand over meeting:

French version has been re-worded to suit customer needs more hence try and move these improvements to the new English master copy. There will be some things which need back and forth work.

Technical terms (inventory has been changed- this will need changing in Transifex on dashboard etc too)

Enterprise-Enterprise permissions needs re-wording
Tags and customer specific permissions pages need work.

Try and remove dependence on embedding shop front.