Documentation meeting 25 July 2024

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.

  • David Nind
  • Heather Hernandez

Apologies

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

  • Kelly McElligott

Updates

Review of action points

  • See previous meeting.
  • MarcEdit section of the manual - move to a wiki page (bug 36990):
    • ACTION: Philip will ask on Mattermost if anyone (maybe koha-US) would like to do this.DONE
      • ACTION: Heather has volunteered for this; she will ask for help from a MarcEdit user at the Koha-US cataloguing group.
      • ACTION: Heather also to check out moving the OCLC Connexion section from the manual to the wiki (and link to the wiki from the manual section)
  • ACTION: Aude and Manu will coordinate a French-speaking Documentation workshop. Date and time TBD. DONE
    • Took place on 9th July (5 participants). Manu also made notes in French on how to update the Manual (to be published on the KohaLa website). https://koha-fr.org/enrichir-le-manuel/
    • ACTION: in 6 month's time, maybe set up another one?
  • ACTION: Aude to send reminders for the general documentation drop-in sessions for Mattermost and the mailing list. ONGOING
  • ACTION: David to check with Chris to see if we have Matomo (or something similar) already setup for page analytics. This is so we can get an idea about which pages are used, and how often. Update: No page analytics are installed.
    • ACTION: David is waiting to hear from Liz if access to the web logs is possible. Will consider proposing setting up matamo.org or plausible.io
  • Ongoing projects - see section below
  • Documentation workflow - see section below
  • Content development guide - see section below

What the team has been working on

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

  • David Nind: Adding release notes for 24.11 bugs - still some way to go. Changing status from "Needs documenting" to "CLOSED FIXED" where no mnaul updates are required.
  • Caroline has been documenting a lot of new system preferences from 24.05.

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 ("click", "go_to", "set_syspref").
  • ACTION: Aude make sure the instructions are up to date! ONGOING
  • ACTION: David to ask Joubu for a login. Have requested.DONE
  • ACTION: Aude to post about automated screenshots to the mailing list and Mattermost. ONGOING
  • ACTION: Aude to update the bug on Bugzilla with information about progress and what needs doing. ONGOING

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

  • ACTION: David to fix a navigation issue for the Using Koha section (currently, the expanded navigation disappears if you are in any of the using Koha sections/chapters). Update: still working on this 8-(.
  • AGREED: We will start with alphabetical organisation of the navigation links, and later on maybe look at grouping by logical topics.
    • ACTION: David to find out if Sphinx has a function to "sort dynamically" for alphabetical sorting in every language, instead of static sorting the way it is now. (As Manu pointed out, an alphabetical order will only work for the English version, as soon as it is translated it will no longer be alphabetical.) Update: Still under action.

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

  • ACTION: Philip to create GitLab issues for each of the points raised in the audit. ONGOING
  • Next priority - fixing the search box:
    • ACTION: David to check the theme to see if it's possible to add a search button to the search box. DONE
    • Outcome: No option in the theme settings for this, so would require custom CSS.

Documentation workflow: issues and ideas

Older Koha versions' manuals

From June meeting:

  • DECISION: We only want to support Koha manuals for supported Koha versions.
  • ACTION: Aude to let Joubu know that the deadline is by 25th September 2024. DONE
  • ACTION: Aude has emailed the general Koha mailing list (what we decided, where and when to download old manuals if people want them). DONE
    • To also notify on Mattermost, the newsletter, and mention it at an upcoming Koha development meeting just in case.DONE

Content Development Guide

Ongoing work to create a content development guide.

  • ACTION: David to take the rules from the documentation style guide and put in the content development page instead. Also to deprecate the style guide page so we don't get confused!
  • ACTION: Philip to check if GitLab has a ruler for "80 characters" in the single edit files in web IDE/browser mode or something similar for line cut off. DONE - See: https://gitlab.com/gitlab-org/gitlab/-/issues/16478
    • DECISION: The 80 character width was a recommendation from Caroline's "best practice" guidelines. It doesn't have to be exact - so can be done by sight! But it's useful for a) people who use an offline editor (so you don't have to scroll to see the full line); and b) for merge requests reviewers (easier to read the diff and to point an error on a particular line).
    • DECISION: If you are using the Gitlab Interface / IDE / single file editor in browser for gitlab: try to roughly stay within the 80 character width, doesn't need to be exact. If you are using VSCode / your own IDE: maybe it has a ruler setting? Ask Aude if you are using VSCode.
  • ACTION: David to research options (possibly instead of using single quotes) if a button text contains an apostrophe. Update: Still under action.
  • 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: Still under action.
  • ACTION: Philip to add a note about how to document permissions to the content development guide (see the work Caroline did with libraries, and [https://koha-community.org/manual/latest/en/html/patrons.html#patron-permissions-defined patron permissions defined). Update: Still under action.
  • 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).
      • We will talk more at upcoming meetings about trying out some actual examples
    • Screenshots (postponed from a previous meeting)
      • Do we need a recommended image size and resolution?
        • We should talk about this again at the next meeting: which browser? at which monitor resolution? What text size in Firefox (100%?)
        • Recommended tools: Greenshot, Flameshot (for Linux and Windows)
        • ACTION for everybody: think about it until an upcoming meeting :)
      • Point to guide on how to write good alt text:
        • W3C Images Tutorial:
          • Good general tutorial about adding alt text for different types of images.
          • Many screenshots are described by the surrounding text, so could be categorised as "Decorative Images".
          • ACTION David: For screenshots, I will ask for some advice in the WriteTheDocs Slack accessibility channel.
        • WebAIM article about alternative text
        • How to Write Alt Text and Image Descriptions for the visually impaired: Making your website and social media accessible to people with blindness and low vision. (An excellent guide, has a great non-technical introduction, and the graphic at the end summarise things really well.)
    • 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
    • ...

Anything else

  • Philip to check with Paul about HedgeDoc for the next Documentation meeting.
  • ...

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_25_July_2024&oldid=34471"