[Koha-docs] a couple of questions about documentation workflows

[David Nind]

Hi Hugh.

Thanks for the questions!

After some time away I'm hoping to get involved with the Koha community
> again. I don't currently work at a Koha-using library, but I still think
> the project is great.
>

I also don't work at or support a library using Koha - it is a great
community and software. Your contributions would be most welcome, whether
it is to the documentation or something else!


> 1. When providing updates to documentation aimed at old versions, should
> the pull request be aimed at a different git branch, or is everything
> simply merged to 'main' and someone else takes care of backporting
> documentation?
>

If the changes can be made to the main branch and can be cleanly merged
without any changes for the older versions, then:
- merge to the main branch
- indicate that this change should also be made to older versions of the
manual as well
==> basically, if there are no conflicts it is easy for the change to be
"cherry picked" into older branches/versions of the manual

If the change only applies to the older branch (for example, has been
rewritten or is totally different in later versions), the merge request
should be against that specific branch/version.

If other changes have been made between the older branch and the main
version that would cause a conflict, then separate merge requests with
changes specific for each branch/version of the manual is required.

2. How are documentation updates tracked between Bugzilla, Taiga, and
> GitLab? Should I be referencing something in commit or PR messages, and if
> so, what should I be referencing? There seem to be many Taiga tickets that
> reference code bugs rather than documentation bugs, for example: should I
> reference the Bugzilla bug in this case, or the Taiga ticket, or both, or
> something else?
>

There are Taiga tasks for each Bugzilla change - these come from the
release notes. Caroline goes through and adds any changes from the release
notes that require changes to the documentation.

Here is the guide on how to ideally label commit messages:
https://wiki.koha-community.org/wiki/Git_guide_for_documentation#Commit_messages

Taiga [number] ([bugzilla number]): [Short title]

Short paragraph(s) that succinctly describe the change
and why the change was made.

At the moment the GitLab issues are used for more management tasks for
generating the documentation, rather than documentation bugs.

Here is a useful starting point for the documentation team
https://wiki.koha-community.org/wiki/Koha_Documentation_Team

One thing I've been trying to do is bring everything together in a Content
Development Guide for the Koha documentation. Ideally, this should make it
easier to get up to speed contributing to the documentation and all the
different aspects (covering the workflow, terminology, content strategy,
and a style guide).

David Nind | david.nind at gmail.com
PO Box 12367, Thorndon, Wellington, New Zealand 6144
m. +64 21 0537 847
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-docs/attachments/20200915/7068fb9c/attachment.htm>