The "one manual" idea
Hello, In the Koha Documentation team, we have been discussing whether we still need one version of the manual per Koha version. The idea being mooted is that having only one manual for all versions in the future may be better. It's an idea that is still at the exploration stage; at this point we would like to get feedback from a wider group of people, hence this message! I included further down a summary of what has been raised so far. We are particularly interested in your thoughts on the following: - What would be impacted if we decided to move to one manual - that we haven't considered yet (see summary)? What issues may arise, who would they affect, what are your suggestions to solve them? - Are there any specific considerations for translated versions of the manual? - Are there any technical considerations that us non-developers haven't thought of? If you have questions, concerns or just think it's a good idea, it would also be nice to hear from you :-) Thanks, Aude [aude_c on Koha IRC] Documentation Manager for the 23.11 cycle Issues with the current situation - The documentation cycle doesn't match the Koha development cycle. It is near impossible for the Documentation team to document all the new features before the new Koha version is released. The manual published alongside the new Koha version is always behind. - When the manual is updated, the update is made to the master branch - the one that matches the numbering of the Koha version currently in development. This master branch isn't visible (unless you know where to find it). It is possible to "backport" updates to older versions of the manual but this is not straightforward. Because we are behind with documenting features, some updates would have to go back through several older versions of the manual, making the process even less straightforward. I'll be honest: it's rare these days when we backport to older versions. - For library teams, that means the explanation of a feature in their Koha version is more likely to be in a newer version of the manual (than in the one they'll land on when clicking the Help button). One manual - why it would be beneficial - Everything in one place: all the latest additions and improvements to the manual available straight away to everyone everywhere. - Translated manuals: only one version to keep on top of. - Easier to manage by the community. How it could work; questions and concerns identified - What if something changes in a newer version of Koha / only exists in some versions but not others? Wouldn't that be confusing in one manual? We would need to clearly mark sections with the Koha versions it applies to, e.g. "until 22.11", "from 23.05". Aude Charillon Customer Services Consultant PTFS Europe aude.charillon@ptfs-europe.com
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@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
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@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@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@inlibro.com https://www.inLibro.com
Hello, Thank you all for your replies. They helped inform the discussions at the 27th September Documentation meeting (https://wiki.koha-community.org/wiki/Documentation_meeting_27_September_2023) We made the most of being twice our usual number in attendance and held a vote on whether to move forward with having one manual for all Koha versions. Attendees unanimously voted in favour! We hope to have one manual from an upcoming Koha version - either 23.11 or 24.05. It is logged on Bugzilla as Bug 34955 - One Koha manual (to rule them all) https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=34955 Caroline did a great job (as usual!) of providing replies to David Liddle's comments. As David joined us at the meeting we were able to cover some of these; and I look forward to discussing the others further in future meetings. Here are a few more replies to Elaine and Lisette's comments. "We run on the latest stable release, and often I find the answers to my questions in older versions of the manual" Would you happen to have an example at hand, Elaine? I would like to understand the situation better. Yes, we would have each section clearly marked with the version in release order (possibly reverse release order; that's to be agreed). For example "From 24.05 version" ; "Up to 23.11 version". Jonathan Druart provided us with a great example of software documentation organised in that way: it happens to be the Weblate manual https://docs.weblate.org/en/weblate-5.0.2/api.html#glossary "Could we maintain one manual, but link to "named version" of older manuals?" I feel like this question comes from the fact I wasn't clear enough in my original message. The answer is no: we won't be maintaining other versions of the manual. We will only have one with indications of versions. As Caroline explained, we already aren't maintaining older manuals. "I'm intrigued, and possibly interested in helping out." :-) Anyone can join the Documentation team! Please do join us at the next meetings (25 October https://wiki.koha-community.org/wiki/Documentation_meeting_25_October_2023 and 29 November https://wiki.koha-community.org/wiki/Documentation_meeting_29_November_2023 have been scheduled so far) to take part in discussions. There is guidance on contributing to the Manual on the Wiki https://wiki.koha-community.org/wiki/Editing_the_Koha_Manual I am also planning online "Documentation for beginners" for the next few months - more information to follow. Finally, at the moment we also have the automated screenshot project, which Caroline shared information on https://lists.katipo.co.nz/pipermail/koha/2023-September/060003.html And I am always happy to be contacted directly! Thanks, Aude [aude_c on Koha IRC] Documentation Manager for the 23.11 cycle Aude Charillon Customer Services Consultant PTFS Europe aude.charillon@ptfs-europe.com Aude Charillon Customer Services Consultant PTFS Europe On Thu, 21 Sept 2023 at 18:29, Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> wrote:
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@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@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@inlibro.com https://www.inLibro.com
_______________________________________________
Koha mailing list http://koha-community.org Koha@lists.katipo.co.nz Unsubscribe: https://lists.katipo.co.nz/mailman/listinfo/koha
In principle, it's an excellent idea. It will be a very big editing job (that's an understatement). We run on the latest stable release, and often I find the answers to my questions in older versions of the manual. How would you retain the old information alongside the updates? Each section in release order? Highlight changes? It will be tricky to set up. But once it's done, it will be easier to maintain. I'm intrigued, and possibly interested in helping out. Elaine VWML <https://vwml.org> On Thu, Sep 7, 2023 at 7:38 AM Charillon, Aude < aude.charillon@ptfs-europe.com> wrote:
Hello,
In the Koha Documentation team, we have been discussing whether we still need one version of the manual per Koha version. The idea being mooted is that having only one manual for all versions in the future may be better.
It's an idea that is still at the exploration stage; at this point we would like to get feedback from a wider group of people, hence this message! I included further down a summary of what has been raised so far. We are particularly interested in your thoughts on the following:
- What would be impacted if we decided to move to one manual - that we haven't considered yet (see summary)? What issues may arise, who would they affect, what are your suggestions to solve them? - Are there any specific considerations for translated versions of the manual? - Are there any technical considerations that us non-developers haven't thought of?
If you have questions, concerns or just think it's a good idea, it would also be nice to hear from you :-)
Thanks,
Aude [aude_c on Koha IRC] Documentation Manager for the 23.11 cycle
Issues with the current situation - The documentation cycle doesn't match the Koha development cycle. It is near impossible for the Documentation team to document all the new features before the new Koha version is released. The manual published alongside the new Koha version is always behind. - When the manual is updated, the update is made to the master branch - the one that matches the numbering of the Koha version currently in development. This master branch isn't visible (unless you know where to find it). It is possible to "backport" updates to older versions of the manual but this is not straightforward. Because we are behind with documenting features, some updates would have to go back through several older versions of the manual, making the process even less straightforward. I'll be honest: it's rare these days when we backport to older versions. - For library teams, that means the explanation of a feature in their Koha version is more likely to be in a newer version of the manual (than in the one they'll land on when clicking the Help button).
One manual - why it would be beneficial - Everything in one place: all the latest additions and improvements to the manual available straight away to everyone everywhere. - Translated manuals: only one version to keep on top of. - Easier to manage by the community.
How it could work; questions and concerns identified - What if something changes in a newer version of Koha / only exists in some versions but not others? Wouldn't that be confusing in one manual? We would need to clearly mark sections with the Koha versions it applies to, e.g. "until 22.11", "from 23.05".
Aude Charillon Customer Services Consultant PTFS Europe aude.charillon@ptfs-europe.com _______________________________________________
Koha mailing list http://koha-community.org Koha@lists.katipo.co.nz Unsubscribe: https://lists.katipo.co.nz/mailman/listinfo/koha
participants (4)
-
Caroline Cyr La Rose -
Charillon, Aude -
David Liddle -
Elaine Bradtke