Bug 32391 - [DOCS] Reorganise the manual contents
Summary: [DOCS] Reorganise the manual contents
Status: ASSIGNED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Main
Hardware: All All
: P1 - high enhancement (vote)
Assignee: David Nind
QA Contact: Testopia
URL: https://docs.google.com/document/d/1K...
Keywords:
Depends on:
Blocks:
 
Reported: 2022-12-02 07:37 UTC by David Nind
Modified: 2024-03-28 12:04 UTC (History)
9 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:


Attachments
Documentation landing page - WIP (105.84 KB, image/png)
2022-12-09 15:05 UTC, David Nind
Details

Note You need to log in before you can comment on or make changes to this bug.
Description David Nind 2022-12-02 07:37:26 UTC
The contents of the manual need reorganising/restructuring.

Currently, the contents is a long list of modules/features/topics in a randomish order.
Comment 1 David Nind 2022-12-02 08:32:56 UTC
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
Comment 2 David Nind 2022-12-02 16:04:32 UTC
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
Comment 3 David Nind 2022-12-09 15:05:06 UTC
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.
Comment 4 David Nind 2023-05-05 18:59:07 UTC
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
Comment 5 David Nind 2023-08-24 23:14:34 UTC
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)
Comment 6 Martin Renvoize 2023-09-27 15:17:50 UTC
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 :)
Comment 7 David Nind 2023-09-27 17:46:11 UTC
(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.
Comment 8 Aude Charillon 2023-09-29 10:07:14 UTC
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...
Comment 9 David Nind 2023-10-25 11:45:09 UTC
Here is a link to a preview (not up to date): https://davidnind.gitlab.io/koha-docs-reorganise/
Comment 10 Heather 2023-11-06 17:29:37 UTC
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
Comment 11 Aude Charillon 2023-11-13 13:51:27 UTC
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!
Comment 12 Heather 2023-11-13 19:09:05 UTC
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!!!
Comment 13 Aude Charillon 2024-03-28 12:04:42 UTC
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)