Documentation meeting 23 October 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:

  • Philip Orr, LMSCloud GmbH, Germany
  • Heather Hernandez, SFMNHP Research Center, San Francisco, CA, US
  • Aude Charillon, PTFS Europe, UK
  • Rasa Šatinskienė, PTFS Europe, UK
  • Stephanie, Montgomery County Public Library

Apologies

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

  • Caroline Cyr La Rose, inLibro, Québec, Canada (vacation)
  • David Nind, New Zealand
  • Emmanuel Bétemps, Bibliothèque de Caluire et Cuire, France
  • ...

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]....
  • H2 (Heather): currently OCLC Connexion Client info moved to wiki, next will update the manual to remove that content, then move on - DONE: OCLC Connexion Client info was moved to the wiki and mentioned in the manual.
    • (next is same process with MarcEdit content, and OCLC Worldshare content).
    • Also started updating instances of “catalogue” and cataloguing" to “catalog” and “cataloging”
  • Philip: Search box submit button added, Bug 31503 trying to decide if it should go in the manual or in the wiki. Maybe in the wiki with a note about it in the sections in the manual (both system preference and OPAC sections). Also the privacy policy / GDPR stuff needs to be added to the OPAC section of the manual. DONE
  • Aude has tried to help out with merge requests. She has also started documenting Bookings - no merge requests yet as it’s going to be a good sized section.
  • David: Worked on Vale and reorganising the manual contents - still a WIP.

Review of action points

  • See previous meeting.
  • ACTION: Aude to check the config file for the manual to correct the copyright statement. It should be updated to remove the date and add a link to GPL. - ONGOING
  • 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 Update: Posted on Koha Community Chat to get ideas. - ONGOING
  • ACTION for Philip and anyone who is interested: check out the W3C Images Tutorial - ONGOING
  • Ongoing projects - see section below
  • Documentation workflow - see section below
  • Content development guide - see section below

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 to post about automated screenshots to the mailing list and Mattermost. ONGOING

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

  • ACTION: David to post a link in Mattermost Chat on the current build - ONGOING

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
  • 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
  • Left side menu in the manual currently has no scroll bar. If you are in a very long subsection with many subheadings, it can be difficult to scroll on the left side. ACTION: Aude will log an issue in Gitlab. DONE see Issue 47.

Documentation workflow: issues and ideas

Any issues or ideas for the general Documentation workflow.

  • Version notes: So far, I (Caroline) have only written the main version where a feature/change happened (i.e. 23.11, 24.05, or 24.11), not the point version (e.g. 23.11.06). That was how I understood the initial assignment. However, there has been discussion in merge request 975 that we should specify the point versions.
    • What should we do?
      • Option 1: Leave as is and continue with main version only
      • Option 2: Change to most precise version
        • Option 2a: Only change the future notes (i.e. note the point version in the version note from now on)
        • Option 2b: Change all the current notes as well as future ones.
          • There are 136 "Admonition:: Version" notes in the manual as of 2024-10-10, not counting the "Attention" notes when something changed, but is not necessarily new.
          • If we are going option 2b, we need to start asap before there are more notes.
          • It's more consistent, but it means we need to go through bugzilla to find all the bugs and find out which version it was backported in.
    • If we change to point versions, how do we decide what goes in the What's new page, and if so, where?
      • If something was introduced in version 24.05 and backported in version 23.11.06, does it go in the 24.05 or the 23.11 section of the What's new page?
      • If something was introduced in version 24.05 and backported all the way to 22.11.xx, does it go in the What's new page at all?
    • If we change to point versions, it means we cannot document something until all the release maintainers have gone over the bug and decided what they do with it. I (Caroline) have come across some features that were separated in several bug reports, where some were in Needs documenting, but others were in Pushed to stable (it is the case for merge request 975, for example, one bug is dependent on another and touches the same prefs). It's the same feature and easier to document in one go (in my opinion), but we cannot do it until all the bugs are in Needs documenting.
    • What do readers need? If they have version 23.11.06 and go looking in the manual for a system preference they have in their system, will they be confused if the manual says the syspref was added in 24.05?
    • Heather suggested to specify in the Manual that bugs may have been backported. Philip also talked about updating the version note wording to make it clearer. All present are happy to stick with using the first version the bug was pushed to (not the point releases it was backported to).
      • DECISION: We will go with Option 1 and add clarification to the manual, see above.
      • ACTION: Aude to add a note at the top of the What’s new page as Heather suggested.
      • ACTION: Aude to update the Wiki to suggest the version note becomes “This feature was first introduced in version 24.05 of Koha.”
  • ...

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) - ONGOING
  • Anything recently added to the page that people want to review or discuss?
    • Bootstrap 5 may add style differences that could be noticeable in screenshots. Since Bootstrap 5 is still being tested / changes still being made, we will wait and if necessary add issues to gitlab / for (possibly automatic by then?) screenshots.
    • ...
  • 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!
      • We should ask in mattermost what resources are people are using
      • It would be good to sort this page by language
      • In the last Documentation Drop-In Meeting, we had some people from Bywater (@catrinab and Sara) who were interested in adding Bywater documentation to the manual - maybe the “Community resources” page would also be interesting for them
        • ACTION Aude: get in touch with them on Mattermost
      • Maybe get rid of the “Other docs” page in the manual: https://koha-community.org/documentation/other-docs/
    • Screenshots (postponed from a previous meeting)
      • Do we need a recommended image size and resolution? DECISION: No.
        • Try to stay at 100% zoom in the browser, only change the zoom if necessary to e.g. show the full table if it would otherwise be cut off
        • Only include left menu in the first screenshot and not for the individual functions
          • already the case for automated screenshots
          • (if you want to think about it in an automated way… make screenshot for the selector that you are talking about ;-) )
        • Recommended tools: Greenshot, Flameshot (for Linux and Windows)
        • ACTION Philip: add this information to the content development guide page in the wiki
      • 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. DONE
        • 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
        • Side menu
        • Top search bar
        • …
    • ...

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_23_October_2024&oldid=34848"