Test major Koha Wiki changes or bug fixes here without fear of breaking the production wiki.
For the current Koha Wiki, visit https://wiki.koha-community.org .Documentation management
Note: these guidelines are work in progress, and documentation managers have the right to change this to whatever they prefer. For now, this will serve as a documentation place for the tasks involved in documentation management.
The Documentation Manager role
Documentation Managers (DMs) perform the task of maintaining the master branch of the manual, which becomes the manual for the next major release of Koha every 6 months. The DM does this by merging merge requests from the documentation team that you deem to be correct and of a high enough standard.
The role of the Documentation Manager is decided by election after each major release. The documentation manager should work closely with the release manager to ensure the manual is of a high standard by the time of release.
A new beginning
The DM will begin their tenure working on the master branch and their predecessor should have branched the last stable branch as their final action.
Before handing over the management to someone else
- Make sure the new manager has maintainer role on Gitlab
- Create the branch for the released version
General tasks
- Lead one documentation IRC meeting per month
- Prepare the agenda
- Send a reminder to the mailing lists a couple of days before
- Chair and lead the meeting
- Run post meeting script (creates new agenda and includes action points, adds to Koha community calendar);
- perl koha-meetings.pl --update --page Documentation_IRC_meeting_DD_Month_YYYY --confirm
- it will ask for your Wiki credentials, then it will ask for Google ones
- Merge merge requests on Gitlab
- Merge into master
- Cherry-pick into maintenance branches for previous versions as required
- Follow release notes updates (https://gitlab.com/koha-community/koha-release-notes) and update Taiga tasks accordingly
Translating the manual
The HTML versions of the manual on koha-community.org are automatically rebuilt on each commit, but do not automatically include translation updates.
The process for updating the translations of the manual, from the start of the release cycle:
1. Setup a new branch of the manual so it can be translated
2. Update the manual page on the Koha Community website
3. Translators translate using the translation server
4. Translation files and preview versions of manual updated each night
5. Translation files for the manual updated (once a month)
6. Update the translated versions of the manual (once a month)
1. Setup a new branch of the manual so it can be translated
To setup a new version of the manual for translation:
1. Create a new branch of the manual from master:
- git checkout master
- git pull
- git checkout -b <manual-branch-name> [1]
- git push
Alternative: create using the the GitLab GUI.
2. Send an email request to the Translation Manager to create a translation project for the new version of the manual in Pootle.
3. When advised by Translation Manager -> TBD/Step 5?
[1] Naming for manual branches: manualYY.MM.x (example: manual19.05.x)
2. Update the manual page on the Koha Community website
Update the documentation landing page at https://koha-community.org/documentation/ with the required changes:
- Add details and links to the latest version at the top of the page.
- Update the development version at the end of the page, if required.
Request the website maintainer to update this if you don’t have access, or request access.
3. Translators translate using the translation server
Translators update the strings for the current and previous versions of the manual using the Koha Community translation server (Pootle), available at https://translate.koha-community.org/projects/
Translators can also use their preferred offline translation tool, and update the files to the translation server.
4. Translation files and preview versions of manual updated each night
Translation files (.po files) on the translation server are automatically updated each night at 1:00 GMT-3.
A script runs that checks for any changes to the translations and uses these to update the preview versions of the manual for translators.
Preview versions of the manual to help translators review their changes and are available at https://translate.koha-community.org/manual/
To check whether this is still current
5. Update the translated versions of the manual (once a month)
1. At the start of each month use https://translate.koha-community.org/tools/ to create a pull request for the versions of the manual to update.
2. Merge request merged.
- Result:** once the translations changes are pushed the HTML files are automatically rebuilt and available on the Koha Community website.
6. Update the translation files for the translation server (once a month)
To work out whether I've got this right or not yet - request at the start of the month after manuals updated?
1. Send a request to the Translation Manager to update the translation files for the manual (start of the month).
2. The Koha translation server is updated with new and modified strings that need translation (magic happens!).
3. Send an email to the koha-translate mailing list to let them know the strings for the manual are updated.
4. Translators translate.
Note: Proposing that the manual files are updated once a month, and not as part of the normal string freeze process (currently have enough work with maintenance and six monthly releases).
TO DO/Questions/To work out/Notes:
- https://translate.koha-community.org/tools/ only shows up to 20.11
- https://translate.koha-community.org/manual/ is not up-to-date
- https://translate.koha-community.org/projects/ has manual projects from 19.05 to 21.05 - at this stage 21.11 is mostly the same as 21.05, so no point yet in translating until progress made on 21.11 changes
Other Wiki pages: