Documentation management

From Koha Wiki
Jump to navigation Jump to search

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 main 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 main 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
    • Create a bug on bugzilla to change the "latest" link to the latest manual, and assign it to Liz Rea
    • In the main branch, change the version number in the conf.py file and the URL in the .gitlab-ci.yml file
    • In the new released version branch, change the "main" in the line starting with "only" to the name of the new branch
  • Send an email to the Translation manager to generate the .po files for the newly released manual

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

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 main:

  • git checkout main
  • 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:

Other Wiki pages:

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Documentation_management&oldid=33841"