Updating the User Guide
How to update and make edits to the OFN User Guide
Check out the background notes and discussions points for the User Guide session at the Global Gathering.
Please note that there are processes in place for updating the User Guide. It's important to follow this process as there could be multiple people making simultaneous changes and we don't want to lose anyone's work. It's also important to because each edit needs to be translated to the other language versions of the Guide. The process is currently being reviewed and revised. See the Discourse post Log and Track User Guide Updates in GitHub to weigh in on the discussion and contribute to the scoping of this solution.
The OFN User Guide is on Gitbooks. To edit the document, you will need a Gitbooks account. Once you have an account, you can be invited to join the OFN organisation.
You can also click on this link to sign up to Gitbooks and automatically be added to the OFN Organisation. Invitation to OFN on Gitbooks
The OFN Organisation on Gitbooks has a number of documents that are organised in language based ‘Spaces’ that are visible when you log in. The OFN User Guide Master document is in English. As well as this document, in the English language space, you will also see the following:
- OFN Super-admin Guide (this document - proposed to be renamed as OFN Instance Managers Handbook)
- OFN Handbook (Processes, Governance, Roles)
- OFN Testing Handbook (Software Testing)
Other instances use the OFN User Guide Master in English as the basis for making updates in their own language. All of the other language guides are visible here in their own Language space. Changes to the OFN User Guide are made first to the English Language Master. Owners of the other language guides then translate the updates into their language version of the document.
Fixes and inaccuracies
If you find a mistake, a typo, an out of date screen grab or something that requires a small fix to make it accurate, you can simply go in to Gitbooks and make that change. It's a good idea to make a comment in the User Guide channel on Global Slack when you do this.
Re-writing Content
If a section of the User Guide requires an update, you can create a draft in Gitbooks and save it, then share a link in the User Guide channel on Global Slack for feedback. Team members from other Instances should have an opportunity to provide input before the proposed new content is Merged.
New features and software updates
If the OFN software has been updated, or a new feature has been launched, the User Guide will need an update. The User Guide updating team will discuss this on Global Slack and plan a content update. (This process is currently under discussion).
Current Process (interim)
- 1.Leave a message in the Global Slack user-guide channel if you'd like a change to be made and one of the core team will make the update for you
- 2.If you make the update yourself, please merge the edit at the time of making the change so we don't have multiple versions and lose changes (see below for how to make changes).
- 3.If you make an update, please notify the whole channel here with a link to the page you changed and information about what you changed and why, so that the owners of other language versions can review and make these alterations too.
You can make changes to the User Guide Master simply by starting to edit the document in Gitbooks. A draft will be created as soon as you make a change. To see your draft, click on Edits in the left hand navigation. A draft can be saved and returned to later to complete. Anyone in the OFN organisation can log in, see and contribute to your saved draft. This is helpful if you're seeking feedback on a draft before publishing. To publish your saved draft, select Merge.
NOTE: there is no warning or confirmation when you click MERGE. Once you hit ‘Merge’ your changes will be published immediately!