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
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.
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.
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 Thus if I fail only a few people will be mad at me ^^
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.
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…
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:
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).
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
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?
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
OFN Team member becomes aware of a User Guide content need
OFN Team member uses User Guide Template in GitHub to create UG issue
User Guide team (maybe?) receive notification of new UG issue
User Guide team member adds issue to User Guide project?
UG issue moves through custom boards in ZenHub (eg. waiting, assigned, review, merged, ready to translate)
User Guide team members self assign issues and move them through boards as needed
User Guide team member closes issue when content is merged (English Language Master only?)
A follow up process for moving through translations perhaps?
CONTENT FOR NEW RELEASE
OFN Dev makes User Facing change to code
OFN Dev adds issue to UG Project at agreed point in Dev Pipe (Ready to Go? Closed?)
User Guide team (maybe?) receive notification of new UG issue
Issue appears in UG Project ready to be assigned (waiting?)
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?)
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
I’m hoping the templates are super easy-peasy user friendly @tschumilas and won’t take people time to fill in.
I’m struggling to get my head round Zenhub and work flows and the rest of it. Is there someone from Product who I can arrange to have a screen share with? @lin_d_hop
@Rachel it would be fab to pick your brains on how/if to integrate this work flow to different language versions of the UG (and so it is not just one for the English version)
Thus if I fail only a few people will be mad at me ^^
