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) lead and coordinate the Documentation team. They are the main contact within the Koha community for anything affecting the Koha manual or related to managing Koha documentation.

The role of the Documentation Manager is decided by election before each major release, alongside the other roles for the next development cycle. The DM will liaise with the release manager and work with other members of the release team.

A new beginning

Previous and new DMs should liaise to ensure the new DM has all the relevant access to systems.

• The previous DM should make sure the new manager has maintainer role for the Koha manual on Gitlab.
  • This is required to merge requests on the manual.
• The current DM should also be given permissions to:
  • edit the Koha community website (check with the release manager for access);
  • add to and amend the Koha community Google calendar (check with the release manager for access);
  • manage the Mattermost Documentation channel (ask a Mattermost system admin to make you the channel admin).
• Access may be removed for the previous DM - or retained to provide additional capacity, in agreement with the new DM.

General tasks

Leadership

• Lead by example, strive to write quality documentation
• Strive to improve editing procedures, suggesting improvements and removing roadblocks wherever possible
• Motivate and support your team members, focusing on the expertise of each person
• Identify prospective documentation team recruits and encourage them to join the team next cycle
• Support and train new documentation team members

Communication

• To the extent possible, the documentation manager is expected to be at documentation meetings and chair them
• Check the mailing list and answer docs questions whenever possible
• Support your team members, answer their questions
• Provide regular updates to the documentation team
• Provide regular updates to the Koha Community
• Work with the wider release team

Documentation tasks

Meetings

• Organise roughly one documentation meeting per month
  • Add the meeting to the Koha community calendar
  • Prepare the agenda on the Wiki
• Send a reminder to the mailing list / Mattermost channel a couple of days before
• Chair the meeting
  • Ensure notes are made from discussions and actions
  • Add notes to the meeting's wiki page
• Update the Next IRC meetings page with the upcoming Documentation meeting.
• Make sure all meetings' Wiki pages have the categories: Documentation; Documentation IRC Meetings; Documentation IRC Meetings YEAR.
  • Tip: to make the meetings appear in chronological order on those category pages, set Options > Categories > Sort this page by default to "Documentation_meeting_YYYY-MM-DD" with YYYY-MM-DD replaced by the actual meeting date in this format.

Maintain the manual

• Coordinate the team members and communicate priorities.
• Make sure projects are progressing.
• Review and merge the commits sent by your team on GitLab. (Tip: enable notifications so you know when new merge requests and comments arrive.)
  • Ensure there are no typos and that the text is concise and easy to read.
  • Check RST formatting is correct.
  • Is this the right place in the Manual for this information? Does it need to be referenced elsewhere?
  • Is the information enough for library staff to use? Does it need anything else?
  • Use the comments in the merge request to ask the documenter to make corrections / additions if needed.
  • Once corrections / additions have been made and the new commits reviewed, merge the request.
  • Ask the documenter to double-check the Manual later to ensure their additions are looking ok.
• Respond to and progress outstanding GitLab issues.
• Review and respond to tasks added to the Documentation component in Bugzilla.

Note: with the one manual (one Manual for all Koha versions, from Koha 23.11), main is the only koha-manual GitLab branch we work on. Any merged requests will trigger the pipeline to run; once it has passed, the Manual will have been updated with the merged commits.

Translating the manual

The Translation manager looks after the technical side of Koha translations and Koha manual translations.

Translations are done using Weblate - see:

• Translating the Koha Manual
• Translation server migration weblate

The Weblate files and the translated Manual are synchronised nightly; any translations done one day should be visible the next day.