Documentation meeting 26 February 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
  • Thomas Dukleth, Agogme, New York City
  • Michał Kula, Poland
  • ...


Apologies

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

  • Aude Charillon
  • Marie-Luce Laflamme, inlibro, Montréal Canada

Updates

What the team has been working on

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

  • ...[Please add an update about you have been working on]....
  • Heather: the MarcEdit wiki page (reformatting into a cool table like David started) & working with Lauren Denny on helping her add a lot of her way cool MarcEdit magic thing
  • There were some requests in the Koha Community Mattermost on making older manual pages more noticeable and less likely to be the first results in a google search.
    • https://gitlab.com/koha-community/koha-manual/-/issues/53 -> David TODO: 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. Michal also suggested dropdowns for language and version selection in the manual. TODO David: have a look at that as well.
    • https://gitlab.com/koha-community/koha-manual/-/issues/52
    • Michal also added gitlab issue https://gitlab.com/koha-community/koha-manual/-/issues/55 for newlines in the .rst files that make problems for (browserside) translation
    • Michal also mentioned the possibility to link from system preferences in Koha to their description in the manual, if they are documented in the manual: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=39249
    • And a request for better searching in the manual: https://gitlab.com/koha-community/koha-manual/-/issues/54
      • On better searching in the manual: docsearch uses a crawler to scrape the pages. Then a script is built for the search engine. https://www.algolia.com/pricing -> Michal says it is actually probably free for open source publically accessible projects. This is docsearch, not algolia itself. See https://docsearch.algolia.com/apply
      • Also see Infrastructure and Plan limits. Is the Koha manual really under 1 GB at the moment, and every record under 10KB? It would be really good to have statistics about how often the manual is currently being searched.. the algolia / docsearch free option is 10k search requests a month. Which seems fine to me, but do we have statistics to back it up? -> see above
      • (Philip): as a legal / privacy noob I'm unsure about what would be important for the Koha community at large, if there are any licensing / legal / privacy problems. https://www.algolia.com/policies/privacy
    • TODO Philip: bring this up at 1. an upcoming Development meeting and 2. an upcoming Documentation meeting.
    • if algolia shuts down, the same indexer can be plugged in to typesense or other search engines (at least its older version, because current one is closed source -- BUT: so many projects use this search nowadays, that if they were to shut down, we can bet on the community figuring it out)
    • Michal also mentioned the Shibuya theme for readthedocs with docsearch/algolia: https://shibuya.lepture.com/extensions/docsearch/ -> TODO David: try it out and show it in an upcoming meeting
  • Philip: Finally added notes to the wiki on documenting permissions, see below
  • Philip: Spellchecking the manual - https://gitlab.com/koha-community/koha-manual/-/issues/23

Review of action points

  • See previous meeting.
    • Caroline ACTION: check if links are possible in the text in conf.py
  • ACTION: David is waiting to hear from Chris if access to the web logs is possible. Will consider proposing setting up matamo.org or plausible.io Update: Posted on Koha Community Chat to get ideas. - ONGOING

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.
  • Summary of actions:
    • ACTION Aude: talk with Joubu about making the results visible so far

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

  • ACTION: David to post a link in Mattermost Chat on the current build - ONGOING
    • Update: Basics looking good so far
    • David to add a merge request!

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 e.g. 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.

  • ACTION: David to research options (possibly instead of using single quotes) if a button text contains an apostrophe. Update: Still under action.
    • ACTION: If anyone finds an example where the apostrophe becomes a problem, please add it to the content development guidelines page!
  • ACTION: David to 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 (link a code linter, but for documentation rules). Update: DONE for this meeting, actual presentation to come at a future meeting :)
    • David showed off a basic implementation using the Google Style Guide, Microsoft Style Guide and RedHat style guide on about.rst, it is used on a local build from CLI with the command "vale". Suggestions and warnings can be set to be ignored so you only see errors. There is a wordlist so that e.g. systempreference names are not seen as spelling errors. Rules are set in .yml files. Not integrated with Gitlab IDE atm since Gitlab doesn't have it as an extension. VSCode has an extension for Vale. It could be used locally or added as a check to merge requests.
    • ACTION: David to look at adding Git Pod functionality to Gitlab at a later date or instead adding it to automatically provide a comment on your merge request in Gitlab - ONGOING
  • ACTION: Philip to add a note about how to document permissions to the content development guide (see the work Caroline did with libraries and patron permissions) - DONE, see:
  • Anything recently added to the page that people want to review or discuss?
    • ...
  • 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 - see SIP2SortBinMapping: https://koha-community.org/manual/latest/en/html/circulationpreferences.html#use-case
      • For workflows that encompass several features, we could have a specific "How-to" / Tutorial section? As a step-by-step guide ("1. do this; 2. do that") which points to existing sections of the manual and re-uses existing screenshot. 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).
        • another 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.
        • another example: Koha installation checklist (Koha-US) - https://koha-us.org/learn/install-config/
        • each “How-to” should be in their 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 Monday Minutes, “Every other…”, french resources… etc. DECISION: Yes, we will do this! ACTION Philip: Create the page in the manual - ONGOING
      • It would be good to sort this page by language
        • WebAIM article about alternative text
        • Guide aimed at social media (will find the link - it is really good)
    • Decision on documenting convention: how do we refer to buttons, what do we call the "Koha side menu", "Koha top search bar"... etc. POSTPONED to next meeting
      • ACTION Philip: decide which quick decisions we want to make next meeting
        • Buttons
        • Top search bar
        • Tip from David: there's a google UI guide that could have helpful information. ACTION Philip: check that out - ONGOING
        • …
    • ...
  • Terminology changes for approval:
    • Use "self-registration" (and variants), not "self registration" (see bug 31270 - signed off).
    • Do not use "borrowernumber" unless referring to the database field name.
    • Use "card number", not "cardnumber" (see bug 38979 - signed off).

Anything else

  • ...

Reminders

  • Find bugs to document
    • Bugzilla search for Keywords=Manual, Component=Documentation
    • Bugs marked with Needs documenting status
  • How to edit the Manual

Next meetings

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