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 [email protected] (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 [email protected] Unsubscribe: https://lists.katipo.co.nz/mailman/listinfo/koha
