Links:
Google Doc
Recording
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
Summary:
- 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
Actions:
- 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 https://www.writethedocs.org/ - 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
- https://www.outreachy.org/ - pays interns that would be available to OFN - can be used for documentation
- Google Summer of Code - https://summerofcode.withgoogle.com/archive/ - unpaid internships
- “I know other OSS tech projects have done user guide projects through google summer of code and outreachy that pay for interns for OSS orgs (https://summerofcode.withgoogle.com/archive/ ; https://www.outreachy.org/) […] Also events like ‘doc a thons’ are popular ways to update docs and onboard people into the orgs/projects”
- “in my previous org we funded user guide updates through DIAL’s grants: https://www.osc.dial.community/stratagrant.html We basically used that money to fund 1.5 full time hours spread across our team to update our docs and do video tutorials and translations for about 6-8 months.”
- 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?
