Log and Track User Guide Updates in GitHub

There was discussion during the Global Gathering Session on Collectively Maintaining the User Guide about establishing a tool for logging and tracking updates to the User Guide.

Updates are required under the following scenarios:

  • An error has been identified, such as inaccurate information or out of date content / screen grabs.
  • When the OFN software is updated, or a new feature has been launched.
  • A section of the User Guide needs to be reviewed / re-written (may not be required ongoing, but currently an issue).

It was decided to explore using GitHub to log User Guide updates that are needed, and investigate whether it might be possible to integrate this with the way issue logging and the development pipe is currently managed on GitHub.

What Problem are we Solving?

Currently there is an informal process for User Guide Updating. If a team member wants to request a User Guide Updates or note that the User Guide is currently inaccurate or needs reviewing, they can post in the User Guide channel in Slack. When a change has been made there is a need for translations to take place. This process is also informal, using Slack. The current informal process carries the following risks:

  • slack comments can be lost over time
  • not all OFN team members are aware of the process
  • the updating team may be unaware of changes that are needed
  • translations can be missed

Some topics for discussion:

  • is GitHub the right platform / tool?
  • what would the workflow be?
  • who could log a User Guide update?
  • what kind of updates would need to be logged

Proposed Process

Please share your thoughts below.

3 Likes

This sounds excellent to me.
The product and design teams are also implementing workflows in Github to go alongside the Dev pipe, and GH allows us to link all these pipes together. So it makes loads of sense that the user guide updates would be managed in a GH repo too. This means that we can manage the flow of features and fixes all the way through from idea to instructions in the same place, which fills me with some kind of administrative joy.

Who needs to be tagged in this to continue?
@lbwright22 @chez @JessC @tschumilas … and others I’m sure?

Would also be great to post this in the #user-guide channel on Slack to ensure people see it, if anyone in the UG circle wants to do that?

1 Like

Sounds great to me. In my head I see the process as:

1. Incoming Changes which generate an issue
These will be a number of sources:

  • Automated link each week or after a product release which refers to the User Facing Changes on the platform.
  • An Instance Manager (ie OFN staff member for any instance) notices a page is out of date or would like to suggest an improvement they can create an issue with a link to the page concerned and information about what they would like changed.
  • Ongoing improvements to the UG (such as adding links to videos, re-writing sections)

2. A member of the UG core team takes ownership of an issue as and when they have time among their other OFN commitments for their named instance.
The issue then becomes ‘in progress: English’

If no change necessary (some releases have no significant user facing changes for example) the issue is closed.

3. The English version of the UG is updated
The page(s) and text/image(s) which have been changed in the English guide are noted.

4. Issue then moves to a ‘translation pipe’.
Each issue can be assigned a tick box list of all the different languages the UG is written in. Managers of the different language versions can check the box when they have updated their UG accordingly.

5. Issue is closed when all translations have been actioned.

Ping @Rachel does this process make sense?

this is brilliant!

I believe that if we move this process to GH, we might want to allow pull request to GH as well? The process would be to review them and merge them if needed. I did that for Leo this week on the Spanish translation.

Another topic but linked: this reminds me that I would like to study the possibility of storing the user guide GH repo inside the main OFN organisation. I will try and test it with the FR guide :grin: Thus if I fail only a few people will be mad at me ^^

1 Like

If folks more familiar with GH think the user guide processes should be linked there - that sounds great to me. And I just want to remind us that not all instances have paid staff time. And some instances (like Can) have very limited paid staff time - and its all allocated to direct support and proposal writing so we can get more staff time and contribute to the global pot. :joy:

So… we need to make sure we allow time and have orientation of some sort so volunteers can enter processes. I"m as concerned about orienting newcommers to our processes than the process/tools themselves. If we are lucky, for example, it will be just one OFN-CAN volunteer who follows user guide updates linked to github, and that volunteer stays with us for a long time. But - it could be that a new volunteer needs orienting every month…

Just a reminder of instance ‘staffing’ realities.

I think @tschumilas raises a good point. We need the process to be a) clearly defined somewhere and b) easy to learn.

The new Support section of the Instance Managers handbook can hold the details so that volunteers can find the information they need to log and action UG changes. I’m happy to write this. In response to Theresa’s concerns, I can’t speak to how easy the GH element of the process might be, as I’m not very familiar with GitHub or how that process might work.

I’m guessing we might create a very simple User Guide Update template along the lines of the below - which would be available to select from when you Add a New Issue in GitHub:

Is this how others see it? @lin_d_hop @Rachel ?

I’m not at all familiar with the next step though, which is how an editor would pick up a task and how it would move through the pipe to completion, as I’ve only seen this from the outside (ie. logging issues, not doing the work).

Can someone else shed more light on this?

2 Likes

Thanks @EmilyRogers for your offer here - I think having the instance management handbook hold the details for volunteers would be fantastic!!

I have written a first draft of the headings / content needed to create a new template in GitHub for User Guide Content. It’s saved in the Global Drive here: https://docs.google.com/document/d/1lcrzX8dwUTdTJk3fY5cWBODmS2Kk_sIdLqgXLAQWyG8/edit?usp=sharing

I’d love some feedback.

I’d also really like some guidance to proceed:

  • How do we create this template in GitHub?
  • Do I need special permissions / is it a dev task?
  • Which GitHub whiz can brief me on GitHub workflows so I can design the process??

Hello Emily

When you have permissions, you have a section called settings > options where you have a button to generate templates:

My ideal set up would be to migrate the gitbook repository into the OFN github organization. This way we could manage access and permissions all in the same place. I will check this out this week and if it is not possible I will just grant you admin access on the ofnuserguide organization.

Re the workflows. I’m not sure what you mean? If it is creating a board with custom columns, this is where Zenhub comes handy. Otherwise you can create projects within github. An example here with the welcome new dev board: https://github.com/openfoodfoundation/openfoodnetwork/projects/27

I suspect I may not have permissions. Is this where I should see Settings?

@EmilyRogers you are looking at discourse I think, not github?

Either way, let’s wait for Rachel’s findings on whether we migrate the repository or not.
Before that we won’t know which organization to edit permissions on, right?

Oops! Too late at night for my brain here :rofl:

yes @sigmundpetersen I won’t manage today but tomorrow for sure :+1:

OK I don’t see Options under Settings in GitHub either… but I will await update from @Rachel!

@EmilyRogers After a few successful dummy tests. I did a first test with the Super Admin guide. Do you see the settings menu at this link: https://github.com/openfoodfoundation/ofn-SuperAdminGuide---Master ?

No - the last link I see is Insights.

I have only been on the ‘logging’ side of GitHub, and have never participated in the ‘assigning Issues/completing work’ side so I’m making some assumptions here as to what the process would be for logging, assigning, working on and completing User Guide tasks. When I say assumptions, maybe I really mean guesses!

That said, here’s a first cut of two scenarios for everyone’s thoughts:

CONTENT UPDATE

  1. OFN Team member becomes aware of a User Guide content need
  2. OFN Team member uses User Guide Template in GitHub to create UG issue
  3. User Guide team (maybe?) receive notification of new UG issue
  4. User Guide team member adds issue to User Guide project?
  5. UG issue moves through custom boards in ZenHub (eg. waiting, assigned, review, merged, ready to translate)
  6. User Guide team members self assign issues and move them through boards as needed
  7. User Guide team member closes issue when content is merged (English Language Master only?)
  8. A follow up process for moving through translations perhaps?

CONTENT FOR NEW RELEASE

  1. OFN Dev makes User Facing change to code
  2. OFN Dev adds issue to UG Project at agreed point in Dev Pipe (Ready to Go? Closed?)
  3. User Guide team (maybe?) receive notification of new UG issue
  4. Issue appears in UG Project ready to be assigned (waiting?)
  5. UG Team member moves issue to Upcoming Releases Board

OPTION 1. UG team member self assigns, and makes change after release
OPTION 2. UG Team member creates new UG Template Issue
(perhaps only for large UG updates?)

  1. UG issue moves through custom boards in ZenHub (eg. assigned, review, merged, ready to translate etc)

I’m aware this is very high level and steps are likely missed and - for those familiar with GitHub - some steps may not even make sense! Please let me know where I can refine the process so that it is clear and simple for everyone to engage with :slight_smile:

I’ve created now a UG team in GH with admin access to all guides repositories. Let me know if it works.