[Koha] The "one manual" idea

Fri Sep 22 05:28:37 NZST 2023

Thank you David,

That is all excellent food for thought! A lot of questions in which to 
sink our teeth into. (I'm using a lot of food and eating idioms... It's 
lunchtime and I think I might be hungry!)

We will have to discuss all of this in the future documentation 
meetings. Here are some of my answers and thoughts to keep the 
conversation going. Anyone can feel free to contradict me or concur with 
me, please do! :)

Distinction between manual and wiki: as I understand it, the manual is 
for Koha end users (librarians, technicians, library clerks, etc.) and 
the wiki is more for Koha developers, system administrators and IT people.

Informal documentation in the mailing list: as far as I know, there is 
no official process to move something from the mailing list to the 
manual or the wiki. When I see that something comes up repeatedly in 
questions, and I have time, I add the information to the manual. We 
should definitely make it a habit of at least creating a bug in bugzilla 
in the Documentation component to keep a trace that this needs to be 
documented.

Switch languages: that is a good idea. I'm not sure how to implement it, 
and the manual translation is currently a saga all on its own. But you 
can definitely change the URL with the language code. I do it all the 
time between fr_CA and en (note that the URL uses the underscore instead 
of the hyphen between the code and subcode (?), i.e. fr_CA and not fr-CA).

Placeholders for new features: that could be interesting. I wonder if it 
would highlight just how much is missing in the manual, haha! We have 
tried in the past to have developers who submit a patch or institutions 
who sponsor a feature to submit at least some documentation with the 
enhancement. It didn't work, but if it was minimal like "Feature A does 
X, Y, Z [this feature needs more documentation]" or something like that 
it might catch on more (that is what is called "dreaming in colour" in 
French).

Voting/prioritizing documentation sections: I think creating a bug in 
bugzilla or commenting on an existing bug is the best way to do this 
currently.

Versioning: what we currently do is that at one point we create a branch 
for the version of Koha in the git repository and that becomes the 
manual version for that version of Koha. As Aude said, we try to 
backport some contributions to older manuals if the feature exists in 
that version of Koha, but it is not officially part of the process and 
it's pretty much to the discretion of the Documentation manager, who 
does everything (we don't have "version maintainers" like Koha has 
"release maintainers"). Some have more time to contribute and backport 
religiously, some don't have as much time and don't backport (most of 
the time it starts as a good intention of backporting conscientiously 
and as the time goes and other things pile on, it becomes less of a 
priority). This is one of the issues that the "one manual (to rule them 
all)" idea is trying to solve.

It is possible to change versions in the URL, as it is with languages. 
It would be interesting, if we keep various versions, to add this 
possibility like switching languages. I don't know what form this could 
take either.

I'm interested in looking into the version banner thing. There are *old* 
manuals floating in Google (like 3.xx) and I think it'd be interesting 
to clean everything up a bit and place warnings on the oldish ones. I 
might need the help of a developer for this.

As for helping, and this applies to anyone willing to help, there is a 
"Needs documenting" status in bugzilla 
(https://bugs.koha-community.org/bugzilla3/buglist.cgi?bug_status=Needs%20documenting&list_id=475125&query_format=advanced) 
as well as a "Documentation" component 
(https://bugs.koha-community.org/bugzilla3/buglist.cgi?bug_status=NEW&bug_status=REOPENED&bug_status=ASSIGNED&component=Documentation&list_id=475126&query_format=advanced). 
Anyone can pick one of those bugs and write documentation. I admit the 
contribution process has a learning curve as we use gitlab and git is 
not something most Koha end users know. The process is described on the 
Koha community wiki 
https://wiki.koha-community.org/wiki/Editing_the_Koha_Manual and we have 
a core team who is willing to teach anyone interested in contributing.

I hope to see you and a lot of new faces in the meeting next week!

Kind regards,

Caroline (off to eat her lunch)

On 2023-09-21 11:34, David Liddle wrote:
> Greetings, Aude—and to the rest of the Koha community following this topic!
>
> You have my sympathy. In my role as IT manager, I have to keep the
> documentation of my environment up to date, and I frequently have to
> consult the documentation of the systems and services that I manage.
> It's not easy keeping pace with constant changes. For example, in
> spite of the vast resources it has available, even Microsoft falls
> behind on documentation for the versions and editions of the software
> and services that it offers.
>
> I think that the pursuit of a single, authoritative manual would be a
> good move for Koha. Here are my thoughts on the Koha documentation:
>
> – Is there a clear distinction between what belongs in the manual
> versus what belongs in the wiki?
>     – There is a lot of informal "documentation" here in the mailing
> list that would be great to have in either the manual or the wiki.
> (Not both.)
> – I think that it would be good to have a means of easily switching
> between languages for any given section—if a translation isn't
> complete or is unclear, the reader can switch to a language that may
> be better. For example, when consulting manuals for Dell products, I
> can quickly switch between English and German when it makes sense to
> do so. Microsoft documentation that has been machine translated
> usually has a little globe icon at the top of the page that allows the
> reader to switch to the original English text. Other online
> documentation that I consult requires changing the language tag in the
> URL, e.g. "de-de" to "en-us".
> – Even if a new feature doesn't have complete documentation, I think
> it would be helpful to insert a placeholder for it so that readers at
> least know that its absence is acknowledged. (You might even advertise
> the need for additional documentation crew!)
> – I have occasionally noticed elements that are undocumented. For
> example, the "SMTP servers" section in "Additional parameters". Might
> there be a way in which new documentation could be requested or
> prioritized through one-click bug reporting or a voting system?
> – With respect to versioning:
>     – If the manual's backend is capable of versioning, won't it still
> be possible to consider a point-in-time snapshot to be "version X" of
> the manual?
>     – If versions of the manual will be preserved, it would be helpful
> to be able to switch easily between versions, as with languages.
>     – If backporting was still carried out under the "one manual"
> concept, I think that it would be acceptable to limit the extent of
> the backports to the version considered "oldoldstable" at the time.
>     – For any version of the manual that is beyond the extent of
> backporting, I think that it would be acceptable to insert a caution
> in the header to the effect, "This manual is current to Koha version
> X. It is no longer maintained. If you see a feature or a process in
> the manual that does not match what you experience in your Koha
> installation, please check the same spot in a later version of the
> manual. (Would the following extension help direct readers?
> http://sphinx-version-warning.readthedocs.io/)
>     – Tagging sections of the manual with applicable versions is a good
> idea, e.g. "Applies to: All Versions", "Applies to: 22.05 and
> earlier", "Applies to: 22.11 and later", etc.
>
> Thank you for soliciting our feedback. If there are elements of
> documentation and the manual that I could support, I think I could
> give some time to that.
>
> Regards,
>
> David Liddle
> System Administrator
> david.liddle at wycliff.de (but not for this list)
>
> Wycliff e.V., https://wycliff.de
> Seminar für Sprache und Kultur, https://spracheundkultur.org
> Internationales Tagungszentrum Karimu, https://karimu.de
> _______________________________________________
>
> Koha mailing list  http://koha-community.org
> Koha at lists.katipo.co.nz
> Unsubscribe: https://lists.katipo.co.nz/mailman/listinfo/koha

Caroline Cyr-La-Rose, M.L.I.S. (she/her)
Librarian | Product Manager

1-833-INLIBRO (465-4276), ext. 221
caroline.cyr-la-rose at inlibro.com
https://www.inLibro.com