Bug 26977 - Update Koha Documentation to use absolute paths instead of relative ones
Summary: Update Koha Documentation to use absolute paths instead of relative ones
Status: RESOLVED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement (vote)
Assignee: Bugs List
QA Contact: Testopia
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2020-11-09 15:10 UTC by Rex Barkdoll
Modified: 2023-07-05 13:26 UTC (History)
2 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact: Caroline Cyr La Rose
Documentation submission: https://gitlab.com/koha-community/koha-manual/-/merge_requests/700
Text to go in the release notes:
Version(s) released in:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Rex Barkdoll 2020-11-09 15:10:29 UTC
Hi,

I'm new to Koha, the previous Koha expert left their position a number of years ago and we left our version running along until the server crashed during an OS update. After that, I had to build a new server from scratch, install and upgrade Koha and get it working. 

I would like to ask that the Koha documentation be updated to make it easier for new people to learn Koha.

Request: Please provide at least one absolute path location (rather than relative paths) when referring to file locations in a section. 

One example is the Cron jobs and Daemons page. I guess under the Cron Jobs subheading, I'm supposed to infer where files are located in the OS based on my flavor, but for someone new like me who is now responsible for becoming the expert on Koha, it would really ease my learning curve to have an absolute path offered at least once on the page. 

The relative paths on the page give me no indication of absolute location and even the Cron jobs description is making a huge assumption as to the user having knowledge that the writer of the documentation does. The text suggests that the files are in misc/ or bin/ but doesn't state that those are to be found in /usr/share/koha/, which would really help. 

Alternatively, a find command suggestion could be offered under the "Cron jobs" subheading for the user to locate the files.

Since Koha files can be found in so many places, a new person like me doesn't know where to look and at least one absolute path to help someone get started and have a little confidence that they're finding the right file would be really nice.
Comment 1 Katrin Fischer 2020-11-09 16:05:57 UTC
I think one big reason for not using absolute paths in the documentation or within Koha is that they can be different depending on how you installed Koha, especially for cronjobs and other scripts. A package, a git based installation or a tarball based installation will all put them in slightly different places. 
Please feel free to jump on the mailing list or IRC with your questons, we are alwas happy to help there.
Comment 2 Rex Barkdoll 2020-11-09 16:51:13 UTC
I understand, but I think what I'm asking for is to add more detailed recommendations to the documentation. 

Throughout my (short) experience with Koha, there's been what feels like disconnect between people who have been using Koha for a long time and people who are new to it, by that I mean people who just know where stuff is based on experience versus people looking for these things the first time. Admittedly, this is an anecdotal assertion based on my experience and what I've identified with in other users' posts on forums, but I feel like I have seen enough people with growing pains to leverage the point.

I believe good documentation is written toward first-timers, and preferably is written in crayon with neon signs pointing the way. Working at a library which services technophobic users, most of our tutorials and guides are written so an elementary school kid could follow along. Even so, our advanced users appreciate that it's hard for them to miss anything and we've tried to over-document to clear up any vague parts before they become and issue.

With Koha, I've had to go to multiple sources and 3rd-party documentation (like Koha geek) to get answers and tutorials to things that really should have been in the official documentation/manual (initial setup, importing a previous koha database, setting up cron tasks, tutorials on XSLR modifications, detailed guides on building reports, etc). What if Koha geek or other third-party resources go away one day?

By no means should the documentation say "this is always where this file will be found," but you could say:

"Depending on your installation method and OS, this files will most likely be found in /usr/share/koha/... OR in /etc/koha/... You can also perform a simple find search if they are not located in either of these directories."

I'm also not asking for the monumental task of changing every URL, just adding a recommended location at the top of each section to point someone in the right direction.
Comment 3 Caroline Cyr La Rose 2023-07-04 21:22:48 UTC
Is this the actual sentence to be added?

"Depending on your installation method and OS, this files will most likely be found in /usr/share/koha/... OR in /etc/koha/... You can also perform a simple find search if they are not located in either of these directories."

I don't have the experience to know where they normally should be. Mine are literally in the root git directory, in misc/cronjobs/... so, exactly what it says in the manual.

I don't mind adding the sentence to the manual, but it needs to be dictated to me :)
Comment 4 David Cook 2023-07-04 23:34:40 UTC
Looking at https://koha-community.org/manual/latest/en/html/cron_jobs.html I see the following:

"The locations below assume a development install which puts the crons in misc/, if you have a standard install you may want to look in bin/ for these files if you cannot find them in misc/"

That could probably be tweaked to something like:

"The locations in the documentation assume a development install where files are found in misc/ relative to the git root checkout. If you have installed using Debian packages or the standard install from source, you will want to look for files in /usr/share/koha/bin/. Other locations are possible with other installation methods."

--

FYI for anyone with shell access using Debian packages, the following command is an easy way to find files installed by a Debian package:

dpkg -L koha-common

This provides a comprehensive listing of the files installed by the koha-common package. You can then easily find the file from there.
Comment 5 David Cook 2023-07-04 23:51:18 UTC
(In reply to Rex Barkdoll from comment #2)
> With Koha, I've had to go to multiple sources and 3rd-party documentation
> (like Koha geek) to get answers and tutorials to things that really should
> have been in the official documentation/manual (initial setup, importing a
> previous koha database, setting up cron tasks, tutorials on XSLR
> modifications, detailed guides on building reports, etc). What if Koha geek
> or other third-party resources go away one day?

Overall, documentation can always be improved but time is money and money is limited.

Installation and initial setup should be covered by https://wiki.koha-community.org/wiki/Koha_on_Debian via https://koha-community.org/documentation/

XSLT modifications would be for advanced users. I'd expect advanced users would be the ones to offer tutorials. That's outside the scope of Koha developers. 

There's a number of resources for building reports listed in the Reports module including http://schema.koha-community.org/22_11 and http://wiki.koha-community.org/wiki/SQL_Reports_Library 

Finally there are a number of free and paid options for support found at https://koha-community.org/support/
Comment 6 Caroline Cyr La Rose 2023-07-05 13:26:32 UTC
Thanks David!

I used your sentence practically as is. I only added Rex's note about using find.

Feel free to reopen if it's still not clear, providing what needs to be changed.

Caroline