Documentation meeting 25 April 2025

From Koha Wiki
Jump to navigation Jump to search

Place

Video conference meeting using Jitsi at https://meet.jit.si/KohaDocumentationMeeting

  • We are using an (open source) video conference platform for the discussion part of this meeting. You don't have to turn your camera on if you prefer not to be seen; but if you are able to use a mic it should make our conversations a lot easier!
  • To join the meeting, click on the meeting link. If you are on a desktop computer, it will open in a browser window; no need to install anything. To join on a mobile device, you will need to download the Jitsi Meet app (from Google Play; from Apple Store).
  • Browsers will ask for permission to use video and audio devices: check or review these settings if you have audio or video issues.

We will use an online collaboration pad to record the meeting minutes, including TODOs and ACTION information.

Time

Attendees

Add your name here if you are planning to attend:

  • Philip Orr, LMSCloud GmbH, Germany
  • David Nind, New Zealand
  • ...

Apologies

Add your name here if you would like to attend but can't make it:

  • Heather Hernandez
  • Caroline Cyr La Rose, inLibro, Québec, Canada
  • ...

Minutes

Minutes for the 25 April 2025 meeting. (HedgeDoc. Log in with your Mattermost Chat credentials.)

Updates

What the team has been working on

Please add an update before the meeting about what you have worked on.

  • Heather: the MarcEdit wiki page (existing content all reformatted into a cool table like David started, and I learned how to do it with the source coding--FUN!) and working with Lauren Denny on helping her add a lot of her way cool MarcEdit magic thing (continuing); OCLC WorldShare Record Manager page created on the wiki, and removal from the Manual happening!
  • ...[Please add an update about you have been working on]....

Review of action points

Note: Excludes action points for ongoing projects and the content development guide sections of the agenda.

Open

  • ACTION - David: Usage statistics for the manual - see if access to the web logs is possible. Also, consider setting up matamo.org or plausible.io. Latest update: Posted on Koha Community Chat to get ideas. ONGOING.
  • Making older manual pages less noticeable, and less likely to be the first results in a Google search:
    • ACTION - David: To contact Chris Cormack to find out who has server access. If we can sort out the website problems, we can get the manual versions redirects sorted out too. GitLab - Issue #53. Latest update:
    • ACTION - Philip: Look at dropdowns for language and version selection in the manual, suggested by Michal in GitLab - Issue #52. Latest update:
  • Newlines in .rst files make problems for (browser side) translation - GitLab issue #55.
    • ACTION - Philip: Is this an accessibility issue? Check in Marseille at Hackfest if there is anybody who uses tools and can check “newer” manual pages (those with newlines). Otherwise, Philip will get back to Michal and explain about our guidelines. Latest update:
    • ACTION - Caroline: Check in a screen reader to see if new lines cause problems. Latest update: Not yet completed (25 April 2025).
  • Linking from system preferences in Koha to their description in the manual, if they are documented: Bug 37624. Latest update: See the bug for progress.
  • Better search for the manual - GitLab - Issue #54.
    • ACTION - Philip (and ask David/Thomas if questions arise): Bring this up at an upcoming development meeting.
    • ACTION - David: Write up a document about improving search for the manual, including pros and cons about using Algolia/Docsearch, and other options such as improving Sphinx search, and Elasticsearch/OpenSearch.
  • Look at updating the theme, Shibuya suggested. Would need to run accessibility checks.
    • ACTION - David: To set up various themes for discussion at a future meeting. Latest update:

Completed

  • ACTION - Caroline: Check if links are possible in the text in conf file - see GitLab - Issue #58. Completed. Changed the footer to a template file rather than using the conf.py. That way we can add whatever we want. You can see the footer in the latest manual. (See merge request 1016). Had problems seeing the copyleft symbol, I tried changing it to an HTML entity, but it doesn't seem to have fixed it for Aude (see merge request 1017). If other people have problems seeing the symbol, I can try to find other options, or remove it. Let me know.
  • ACTION - Caroline: Add an academy bug for the three terminology changes - self-registration, use of borrowernumber (only use if referring to the database field name), card number. Completed.
    • Bug 39454 - Change "self registration" to "self-registration" (space to hyphen)
    • Bug 39455 - Correct "cardnumber" to "card number" (when referring to the patron's card number, unless it's the database column)
    • Bug 39456 - Change "borrower number" to "borrowernumber" (when referring to the database column)

Ongoing projects

Automated screenshots (Jonathan, Caroline, Aude) - Bug 34076

  • If we need more logins for the screenshot page, contact Joubu.
  • See the Guidelines document on the Google Drive for instructions.
  • ACTION - Philip: Talk with Joonathan in Marseille about making the results visible so far. Are we continuing with it? Can we do something with what we’ve already done? Latest update:
    • Jonathan will try making something with it, maybe even for 25.05.
    • Jonathan wants to continue with it and suggests putting a task on your schedule and doing one screenshot a week. Or one a day if you can. Also Philip could ask on Mattermost for more people to join in.

Re-organising the manual (David Nind) - Bug 32391 - Preview

  • ACTION - David: To post a link in Mattermost Chat to the current build.
  • ACTION - David: To add a merge request this week.

Accessibility issues in the Manual (Philip and team) - Wiki page

  • ACTION - David: To look at controlling the focus order on manual pages (e.g. skip links for the left side menu - can we override Sphinx’s html builder?) - ONGOING better to check after re-organising. Could also be dependent on the theme, for example if it is changed to Shibuya.

Documentation workflow: issues and ideas

Any issues or ideas for the general documentation workflow.

  • ...

Content Development Guide

Ongoing work to create a content development guide.

Current actions

  • ACTION - David: To research options (possibly instead of using single quotes) if a button text contains an apostrophe. Latest update: still under action.
  • ACTION - Everyone: If anyone finds an example where the apostrophe becomes a problem, please add it to the content development guidelines page!
  • ACTION - David: Demonstrate Vale at an upcoming meeting. This is a way to check the manual to identify content that doesn’t comply with our content development guide rules (like a code linter, but for documentation rules). Latest update: Still under action, presentation to come at a future meeting.
  • ACTION - David: To look at adding GitPod functionality to GitLab at a later date, or alternatively look at running Vale automatically to provide a comments on merge requests in GitLab. ONGOING.
  • ACTION - Philip: Wait to hear from David about possibility on using Vale for future merge requests as a spellchecker, style guide, and so on.

Recent changes for review or discussion

  • Anything recently added to the page that people want to review or discuss?
    • ...

Topics to cover

  • Topics and questions to cover (please add yours!)
  • Use cases: how can we include more of these to better show how Koha features are used together? (Postponed from a previous meeting.)
    • For use cases specific to one feature: insert as another section - as an example, see SIP2SortBinMapping
    • For workflows that encompass several features, we could have a specific “How-to”/Tutorial section. These should be a step-by-step guide (“1. do this; 2. do that”) that point to existing sections of the manual and re-use existing screenshots. Will need to be mindful not to re-create the FAQs and the reasons why we thought they were not relevant anymore (make sure we date/version the workflows and review them).
    • Example: When a library has to close unexpectedly, what do they have to do?
      • Things like: calendar update, postponing issues and holds, adding a message to the OPAC, etc.
    • Example: Koha installation checklist koha-US - Installation & configuration
    • Each “How-to” should be in its own page.
    • We should also add links to the “Monday Minutes”, "every other… " videos, etc.
    • We will talk more at upcoming meetings about trying out some actual examples.
  • We should add a general “Community resources” page to the manual containing links to ByWater Solutions’ Monday Minutes, “Every other…”, French resources, etc.
    • DECISION: Yes, we will do this!
    • ACTION - Philip: Create the page in the manual - ONGOING.
    • ACTION - Philip: To create a “How to” section in the manual with an example page for a sample How-To -> David will incorporate it into his template changes.
    • Notes: It would be good to sort this page by language.
  • Decision on documenting conventions: how do we refer to buttons, what do we call the “Koha side menu”, “Koha top search bar”… etc. POSTPONED to the next meeting. ACTION - Philip: Decide which quick decisions we want to make at the next meeting - Buttons, Top search bar. ACTION - Philip: Check out the Google UI guide - ONGOING

Terminology changes

Anything else

  • Drop in sessions - are we planning any for the next few months? (David Nind)
  • ...

Reminders

  • Finding bugs to document:
    • Bugzilla search for Keywords=Manual, Component=Documentation.
    • Bugs marked with Needs documenting status.
    • All beginner-friendly documentation bugs are listed under the documentation component in Bugzilla with the academy keyword, or use the academy keyword search.
  • How to edit the Manual

Next meeting

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