The contents of the manual need reorganising/restructuring. Currently, the contents is a long list of modules/features/topics in a randomish order.
Here is a rough outline of what I am thinking about. Tasks: - Fine tune the revised contents/structure - Make available in a shared document for comments/interactive feedback - Reorganise the index page for feedback (make available as a static site) Potentially each of the sections could be separate guides, rather than one big manual, with the contents page organising and linking these together. Initial focus would be on reorganising the contents, and then later reorganising content in individual sections/chapters/guides where required - including adding new sections. Revised contents outline, with notes ==================================== Using this manual/documentation [about the documentation and how it is organised] - Conventions - Change log [quick notes on what has changed in the documentation, for example a new guide on a new feature added] What's new in Koha [more user-friendly 'release' notes] Koha overview [brief introduction to Koha - key features, modules and tools; the community] Getting help Part X - Getting started [brief outline of process to consider when implementing, with links to more detailed information/guides/tutorials] - Implementation [including links to the checklists] - Data migration - Installation - System setup and configuration - System administration [including managing upgrades] Part X - Using Koha [sections/chapters/guides on each of the modules, tools and other features - not sure of the best way to group or organise this yet] - Finding your way around [getting familiar with the OPAC and staff interface] - Searching [may be an advanced search guide as well?] - Patron guide to using the OPAC - The core modules: . Circulation . Patrons . Cataloging . Authorities [combine with cataloguing?] . Serials . Acquisitions . Reports .... - Other modules, features, and tools [not sure how to group yet] . Course reserves . ERM . Interlibrary loans . Lists . News . Notices and slips . Patrons . Point of sale .... - Enhanced content, integration, and web services [separate sections or part of above topics where appropriate] - Customising the OPAC and staff interface . Look and feel [theming] . JavaScript and CSS Part X - Implementation guide Part X - Data migration guide [getting your data into Koha] Part X - Installation guide Part X - System setup and configuration - Using languages other than English Part X - System administration - Backups - Security - Scheduled jobs [cron jobs] - Search engines - Upgrades Part X - System preferences [Reference] Part X - Cron jobs [Reference] Part X - Package commands [Reference] Index Glossary License information
I've created a document that anyone should be able to comment on (no login required): https://docs.google.com/document/d/1KyrsMVWG_kcVvbFsUkysRC9oovIbFCNTNgCwSyM4SL0/edit?usp=sharing If you prefer not to use a Google document, you can use https://annuel.framapad.org/p/koha-manual-contents-reorganisation Quite a few changes from comment #1 - more a narrowing down of the top-level items: Introduction Koha overview What's new in Koha Getting started Using Koha [where most of the content is]: - Core modules: Circulation, patrons, etc - Other modules, tools and features - Enhanced content - Customising the OPAC and staff interface - System configuration - System administration Implementing Koha Installing Koha System preference [reference] Glossary Index
Created attachment 144530 [details] Documentation landing page - WIP This is a screenshot, just to show some current progress. Working through each existing section and adding it under the relevant heading.
I've asked for feedback on the proposed contents on the development list - will ask on the main list after I've incorporated any feedback and discussed further with the Documentation Team. Link to message: https://lists.koha-community.org/pipermail/koha-devel/2023-May/048138.html
I didn't really get any feedback at the time I posted to the development list. Since it was a while ago, and there are more Documentation team members, I'll add to the agenda for the next documentation meeting (https://wiki.koha-community.org/wiki/Documentation_meeting_27_September_2023)
The one caveat I see here is that we'd need to carefully test the contextual linking from inside Koha to the manual.. But I like the look of the screenshot so far :)
(In reply to Martin Renvoize from comment #6) > The one caveat I see here is that we'd need to carefully test the contextual > linking from inside Koha to the manual.. But I like the look of the > screenshot so far :) Thanks Martin! Most of the initial changes are on the main index page, so shouldn't affect the content pages at the moment. But definitely will keep in mind if any of the content pages are changed, and new pages added.
Sorry, just realised I forgot to comment on the bug itself! (doh) The feedback from the 27/09 Documentation team meeting was: "It looks good, please go ahead"! And also: thank you for looking into this. We'll probably want to re-organise the sub-sections in more depth at some point, but that will be something for later...
Here is a link to a preview (not up to date): https://davidnind.gitlab.io/koha-docs-reorganise/
Hi! I'm looking at: Using Third Party Software With Koha > OCLC Connexion Gateway I would like to rename that: OCLC Connexion Because only bibs can be transferred to Koha via the Gateway interface, and the section also includes instructions for using batch export from Connexion and Stage MARC Records import in Koha. Also, right now, there are two interfaces on the Connexion side: Connexion Browser (Until 30 April 2024) and Connexion Client (now and in the future). Resources like the Wiki refer to the Browser, e.g.: https://wiki.koha-community.org/wiki/OCLC_Connexion And I think the manual could be clearer if this section were just, "OCLC Connexion," and then this section within it: Setting up your OCLC desktop client Were changed to: Setting up your OCLC Connexion Client OCLC Connexion Browser is no longer supported by OCLC as of 30 April 2024. OCLC Connexion Client is desktop software available from OCLC to subscribers. After it is downloaded and installed, to set up the OCLC Connexion Client for use with Koha, go to... I think this would make it clearer to those unfamiliar with OCLC that it is a paid, subscription service and the Client is the required desktop software, which must be used to get the MARC records from OCLC. So I think this is an example of a section that is ideal to be a "separate guide" and I'd like to work on the content now that the software interface is changing for a lot of libraries (from the Browser to the Client). I think it's in a good place, under "Using Third Party Software With Koha." Cheerio! h2
Thanks Heather! It looks like some of your proposed changes that concern the Manual could be done in the existing page - without the need to wait for David's re-organisation. Happy to have a look at it together if you need some guidance!
That would be great, Aude!! I'll get my thoughts and notes together and be in touch--it would be so helpful to look at it with you--I am such a newbie with the manual and would appreciate your guidance! Thank you!!!
To note: as agreed at the February 2024 Documentation meeting, the What's new page has been added to the Manual side navigation. (Merge request 842 https://gitlab.com/koha-community/koha-manual/-/merge_requests/842)
Just adding a link to an old preview I created - I just realised I hadn't added that to this bug. Preview link: https://davidnind.gitlab.io/koha-docs-reorganise/ Note: This is for an older version of the manual! Update on progress (as at 25 June 2024): 1. Most of it is working as I intended (and as set out in the Google Doc - see the URL link for the bug), apart from the navigation for the "Using Koha" section. 2. For whatever reason, when you click on Using Koha > then a section (such as Cataloging), the expanded menu under Using Koha disappears and you only see the top-level sections. 3. I spent a few days trying to figure it with no success, and then put it aside for a while (was very frustrating!). To do: 1. Sort out the navigation issues for "Using Koha". 2. Sort out each section page, and update the content where required.