Global Gathering 2020 - Day 8 - Collectively Maintaining the User Guide

Tags: #<Tag:0x00007fe427910740> #<Tag:0x00007fe427910678>

Google Doc

Notion notes:

What is the purpose of this session?

The User Guide team is growing, which means we have greater capacity to keep the user guides up to date, and expand. This session is to discuss improving our systems for managing this workload.

What outcomes/deliverables do we want?

A clear system for managing the work of keeping the various User Guides up to date

Who is facilitating? Bato + Emily

Who is scribing? Gen


  • Louise explained the history of the User Guide development
  • Louise explained what the process is now: Louise and Emily make small changes to the User Guide iteratively as they become aware that information is missing or inaccurate. They also take turns reviewing the weekly release notes and updating the English-language Master Guide on this basis. They then post in Slack to let other instances/language guide users know so they can propagate the update.There is also an ad hoc process for reviewing and re-writing dated sections of the User Guide.
  • We discuss potential new avenues of development: How To guides; videos
  • We also discuss the possibility of hiring a dedicated User Guide person, with language skills, or getting grant funding for existing team members’ time


  • Seek further information about the grants that Eriol mentioned (Eriol)
  • Onboard Misra & Jess, and possibly record this session (Louise & Emily)
  • Team to provide feedback on Rachel’s question on Discourse about translations (All)

Actions needing an owner

  • Establish a system for tracking User Guide tasks to be done in Github/GitBook (?)
  • Task for global fundraiser - apply for these documentation-specific grants (?)
  • Agree and document UG editing process and roles, including rolling out edits to all languages and how the tasks are shared/distributed across the team (?)
  • Create onboarding documentation for UG editors (?)
  • Next steps for creating / fundraising to create video content (?)

Detailed notes:

Current process - Louise

  • Explains the background of the User Guide team
  • Different instances had their own guides, structured differently, no clear system on propagating updates across these different guides
  • Published English-language “master guide” in January
  • Now question is how to establish a system for ensuring the master guide is always updated with weekly releases, and able to be updated iteratively with new information
  • User guide used to be 90% out-of-date, now 90% up-to-date at any one time
  • Plans to add extra sections - e.g. complementary software - as well as extra resources, like videos
  • Current need to review and rewrite some sections that are incomplete e.g. Reports.
  • Louise also wants to add a sort of a How To section - problems that often arise for users that require knowledge across a few different OFN platform functions
  • Myriam question: how are other language guides updated today?
    • Louise posts in Slack when the Master Guide is updated, leaves it to instances to update the other language guides

Onboarding of new members (Jess and Misra) - Louise

  • Emily suggests we could create onboarding documentation and / or a video walking new team members through the User Guide processes
  • Jess suggests it depends on how much more the team is going to grow - could just record the training session for Jess/Misra and share this for new people
  • Louise reckons we do need more people on the team, so onboarding resources would be good

Potential new process

  • Myriam suggests that we could pay a language student a few hours a month for ensuring translations are accurate. Concern re: defaulting to English being the master version - can make more sense for members with other languages to update their own language guide and propagate to the English version.
  • Emily suggests we might have 1-2 people responsible for each language version to ensure consistency of language, voice, tone
  • Rachel: “We need to be careful about translation: there is a difference between translating and really explaining to someone a feature that you know about.”
  • Emily draws attention to a potential trade-off here. When a user question highlights an inaccuracy in the guide, it’s nice to be able to fix it on the spot. A heavy process of updates, translations, etc. will introduce a gap.
  • Rachel points out that it’s hard to find time to update the user guide when dealing with day-to-day work, responding to user queries, etc.
  • Myriam: maybe we can simply cc the person/people responsible for the user guide on these emails?
  • Eriol suggests implementing a bounty system for doc/translation issues. But Myriam argues that we need someone committed over time.
  • 2 separate issues:
    • Information architecture - long term iterations of the User Guide(s)
    • Content evolution and translations - short term updates we need to develop a process for
  • Eriol draws our attention to - a community of “technical documentation nerds”
  • Louise: maybe we can identify sections that are highly used which we could start with for making videos/alternative resources
  • Emily: So we’re homing in on an agreement that we will all update the user guides on the fly, but also try to find resources for a dedicated user guide reviewer?
  • Rachel: suggests we need to be careful about constructing our process around a new hire when we don’t know if we can pay for that role.
  • Eriol mentions the DIAL grants to help with documentation (strategic / catalytic grant) which provide funds. (ie. hosting, creating content, archiving videos etc). Eriol’s previous experience was that 200k + was made available to pay for various team members
  • Myriam - ok, so maybe we could use funds like this to pay existing team members to do this work
  • Parked this discussion here

What is the process for updating after weekly releases?

  • Weekly: Louise and Emily take turns checking the release notes on the weekly software update
  • Would be nice to share the load of implementing these updates in the guides
  • Louise emphasises that it doesn’t have to be the English guide that is updated first - whoever takes the implementation task can do it in their own language first and then others will imitate the change in their own language guides
  • Rachel raised that we need to decide how to maintain the other language versions in Gitbooks. This is open for discussion in Discourse: Translating our userguides - take 2

How do we track what needs to be updated?

  • Emily created an example of what a Content Tasks tracker might look like (example in Notion, but hesitancy about adding a new tool like Notion - what is the right tool?)
  • Could implement this in Github/GitBook - could be part of the workflow for devs to trigger a new task with each release
  • Louise highlights that “Lynne suggested using github. Adding updating the UG to the issue after release as an extra step”
  • Important thing is ensuring the tasks are all in one place

Discussion of how-to videos:

  • Would be linked from user guide, and aggregated on the Youtube channel where users who prefer video learning could watch through as many as they like
  • One issue would be language support - if just subtitles might not be useful for learners who specifically find learning through reading difficult
  • Could use grant funding for doing videos in different languages / dubbing?
1 Like

Following on from discussions last week I have had a look at the current User Guide sections:

  1. Welcome to the OFN User Guide
  2. Local OFN organisations and contacts
  3. Where does my business fit in OFN?
  4. Quick Start Guides
  5. Features
  6. Complementary Software and Tools
  7. Hub Management Tips
  8. Troubleshooting
  9. Glossary of OFN terms
  10. Feedback

I think there is work in the following areas that could be benefit for all:

  • Add in ‘Farmers Markets’ to the Quick Start Guide section (especially to help Canadian and USA enterprises @tschumilas @JessC @lauriewayne1 @apb )
  • Under Features the Reports section needs completely re-writing (when the changes have been implemented on the platform- not yet!)
  • The Complementary Software and Tools section is mainly empty. Does anyone have scope to add to this? Mailchimp, accounting software, …
  • I would like to change the ‘Hub Management Tips’ to ‘How to’s’ which would encompass how to solve specific user problems (such as step by step how to set up an early shopping hour for elderly customers), as well as social media tips. As a stop gap the UK have a lot of marketing docs to advise users now and we could add them here for other enterprises to view (not ideal in document rather than editable form, but a start).
  • I would like to add a section ‘A shopping guide’ aimed at people using OFN to shop local. In the UK we are often asked for this and it would be nice to have somewhere to point them to. I suspect other countries around the world would also benefit to having a place to explain how a customer registers with OFN, what happens if you are a customer and have a subscription etc etc. (This would need to wait until after last Mobile UX release at end of Oct 20)

All thoughts welcome! (and volunteers for doing any of the work :slight_smile:

@Rachel @MyriamBoure @EmilyRogers @chez @Bato @thomaz


@Cecilia-Hn @Jo_daSilva @lin_d_hop @NickWeir @romale @Erioldoesdesign @Jana :point_up_2:

1 Like

Great thoughts @lbwright22 - you are a powerhouse!

I think the proposed new sections sound like quick wins as we have some existing content to work with:

  • Quick Start Guide - Farmers Markets
  • How To’s
  • Shopping Guide

In Aus we have some existing Farmers Markets content and the beginnings of a knowledge base and email templates that could be repurposed to a How To format. I wonder what is the best tool for collaborating on creating this content. I don’t feel like GitHub is the best collaboration tool for creating from scratch, incorporating feedback and comments etc. My instinct is to reach for Google Docs and start writing/dumping/editing. Is that how others see it?

As an aside, I don’t believe I have access to the OFN Global Google Drive. Anyone know how I could arrange that??

I think I can grant you access to the Drive @EmilyRogers.
Is it your OFN email address you would like to use with it?

1 Like

Yes please @sigmundpetersen that would be awesome -