Bug 30998 - [DOCS] Managing documentation tasks - simplify processes and integrate more with the development process
Summary: [DOCS] Managing documentation tasks - simplify processes and integrate more w...
Status: ASSIGNED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: master
Hardware: All All
: P1 - high enhancement (vote)
Assignee: David Nind
QA Contact:
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2022-06-20 20:31 UTC by David Nind
Modified: 2022-06-23 20:06 UTC (History)
12 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
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 David Nind 2022-06-20 20:31:08 UTC
The process for choosing areas and things to document is confusing. This makes it more difficult (particularly for new contributors) to find a list of what to work on. 

This bug looks at options for simplifying this, and to try and integrate the process more into the other community processes and Bugzilla.
Comment 1 David Nind 2022-06-20 20:36:39 UTC
Message from Martin Renvoize on 16 June 2022 (hope you don't mind me adding this here...):

"I was chatting to our staff today and they're still keen to contribute to the manual, but are also still finding the process confusing especially with regards to choosing area's to document and when.

I came up with a proposal a little whilst ago to try and integrate the process more into the other community processes and bugzilla.

Would it be helpful/useful to add a 'Ready for documenting' status in Bugzilla that sits between 'Pushed to X' and 'Resolved Fixed' and encouraging the Release maintainers to use that when they make the decision to not backport instead of the current 'Resolved fixed' change.

This would allow for building a queue automatically on dashboard.koha-community.org for documentors to work through much like the testers and the QA team do.  So one would look at the list, work on docs submissions and then update the bugzilla status to 'resolved' upon completion (or upon making the decision that documentation updates are not needed)?

Just a thought.. I'm happy to do the bugzilla admin changes and update the dashboard.  What do you think?"
Comment 2 David Nind 2022-06-20 20:38:27 UTC
That sounds good to me.

TLDR; Add a new bug status(es) to Bugzilla (such as Documentation Needed and Documentation Updated) so we easily create a list of documentation tasks that need working on, and have this information included on the dashboard (similar to sign-offs).

At the moment, we can use these keywords in Bugzilla:
- Manual
- Manual-updated

The process I intended to use is to "manage" documentation tasks:
- Have an overall bug for each release with a spreadsheet, for example see bug 29640
- Update the spreadsheet each week with changes pushed: review and decide whether documentation changes are required, update release notes for non-technical changes
- Update the bugs where documentation changes are required with the 'Manual' keyword
- Bugzilla report that lists all the bugs for a release that need documentation, for example:
https://bugs.koha-community.org/bugzilla3/buglist.cgi?cmdtype=runnamed&list_id=414423&namedcmd=Manual%20update%20required%20-%2022.05

I had been thinking of getting another keyword added: 'Manual-no-update-required' (or something similar), as this would make it clearer that it had been reviewed without having to look somewhere else.

However, having a status, such as 'Needs Documentation' or 'Ready for Documenting' would make everything a lot cleaner.

Questions:

1. Would it be possible to have a 'Documentation Contact' field, like there is for the QA Contact. That would mean the team (or anyone) can assign themselves to the documentation task.

2. How would this work with the current developer work flow: release manager pushes to master, release maintainers push to their versions
   - who changes to "Needs Documentation" (documentation manager?)
   - after the documentation changes are made, do we need another status like "Documentation Updated"
   - who would change to "RESOLVED FIXED" (is this changed at the end of the release cycle, or continuously once pushed to a maintenance release?)

So, the work flow could look like this:

1. Bug pushed to master and maintenance releases (bugzilla status = Pushed to X) (release manager and release maintainers)
2. Decide if documentation updates are required (bugzilla status = Needs Documentation) (anyone, Documentation manager - review pushed bugs regularly)
3. Appears on dashboard, like Needs Signoff and Needs QA
4. Documentation team (any anyone else) assigns themselves as the Documentation Contact
5. Documentation updated (edit content, create merge request, changes merged, comment added to the bug that doc changes made, follow-up change if required from any feedback)
6. Once documentation updated, status changed to 'Documentation Updated' (not sure on this step - but it would be nice to have something like Signed Off - [Month/Year] on the dashboard)
...repeat until there are no more documentation tasks!..

I had thought about using a third party tool, like Trello, or go back to Taiga.io, or use the issues tool in GitLab (my second preferred option over using Bugzilla) - but having one tool, and not needing to manually duplicate or maintain something else is the ideal.

Ideally, the end result of any changes would be:
1. Documentation team members: list of documentation tasks to work on (list in bugzilla)
2. Community: dashboard showing documentation tasks where work is needed, and documentation updated (like sign-offs)
3. Documentation manager: easy way to maintain list of documentation tasks (change bug status in bugzilla after reviewed)

Anyway, thoughts welcome! (And thanks Martin for starting the discussion!)

Will add to the next documentation team meeting agenda to confirm anything we decide from this discussion.
Comment 3 Martin Renvoize 2022-06-21 09:39:39 UTC
(In reply to David Nind from comment #2)
> 1. Would it be possible to have a 'Documentation Contact' field, like there
> is for the QA Contact. That would mean the team (or anyone) can assign
> themselves to the documentation task.

I love the idea of a 'Docs Contact' field. I can certainly add one, but I can't link it to users the same way 'QA Contact' works :(. (I'll submit a bug upstream to the bugzilla devs for this, I've often found myself wanting that)

> 2. How would this work with the current developer work flow: release manager
> pushes to master, release maintainers push to their versions
>    - who changes to "Needs Documentation" (documentation manager?)
>    - after the documentation changes are made, do we need another status
> like "Documentation Updated"
>    - who would change to "RESOLVED FIXED" (is this changed at the end of the
> release cycle, or continuously once pushed to a maintenance release?)

The guidance right now is for Release Manager to use 'Pushed to master', then the Release Maintainers watch for that and as the backport they use 'Pushed to X' and if they make the decision not to backport then use 'Resolved Fixed'.  My proposal is that the Release Maintainers simply switch from using 'Resolved Fixed' to 'Needs Documenating' as they're 'Final status'.

> 2. Decide if documentation updates are required (bugzilla status = Needs
> Documentation) (anyone, Documentation manager - review pushed bugs regularly)

I was thinking lets spread the load for this decision. Rather than requiring the docs manager to review all bugs, we produce a list of the dashboard using the new status and docs team members work through the said list marking themselves as 'Docs contact' and updating the status to the next step as appropriate (which may well be a simple switch straight to 'Resolved fixed' when they deem a bug doesn't actually need any documentation changes)

> 6. Once documentation updated, status changed to 'Documentation Updated'
> (not sure on this step - but it would be nice to have something like Signed
> Off - [Month/Year] on the dashboard)
> ...repeat until there are no more documentation tasks!..

I had only envisaged adding 'Needs documenting' or similar, but we could easily track progress with an additional state.. so 'Pushed to X' -> 'Needs documenting' -> [ 'Resolved fixed' | 'Documentation submitted' ] -> 'Resolved fixed'

Adding the 'Documentation submitted' option would allow for the docs manager to have a list to work through in a similar fashion to the QA team's todo list (though simply having gitlab submissions may serve the same purpose for the Docs manager.. so I'm not sure how helpful it is?)

> I had thought about using a third party tool, like Trello, or go back to
> Taiga.io, or use the issues tool in GitLab (my second preferred option over
> using Bugzilla) - but having one tool, and not needing to manually duplicate
> or maintain something else is the ideal.

I'm not at all against third party tools (and I'm not always the biggest fan of Bugzilla.. I'm just thinking that folding it in to the existing infrastructure may make things clearer to the wider community and userbase maybe?  I'm also all for automating or making things second nature process-wise rather than burdening anyone individual with a maintenance task.. maintaining an external tool is always difficult.. bugzilla has served as a pretty nice central place for data so if we can bend it to our will here and just use the info that's already in it I think that's a step forwards.

> Anyway, thoughts welcome! (And thanks Martin for starting the discussion!)

It's been a pleasure.. I'm always open to discussions and trying to help move processes forward.

> Will add to the next documentation team meeting agenda to confirm anything
> we decide from this discussion.

Excellent.
Comment 4 Martin Renvoize 2022-06-21 09:50:34 UTC
Adding current RMaints to the discussion as this would be a minor change to their current workflow (as detailed on the wiki:https://wiki.koha-community.org/wiki/Release_maintenance)
Comment 5 Martin Renvoize 2022-06-21 10:57:14 UTC
OK, I've had a go at implimenting a first draft of this.. we now have a 'Needs documenting' status between 'Pushed to X' and 'Resolved' in bugzilla and I've updated https://dashboard.koha-community.org/ to display this new state in the 'To Do' area and under 'Bug statuses'.

Obviously, the status is not yet set for any bugs at the moment; thus, the lists are empty... but it should give an idea of how it would look and give people a clear way to get started on picking what to document.
Comment 6 David Nind 2022-06-21 11:06:35 UTC
Thanks Martin for all your work on this!

I'll start reviewing and adding 22.11 bugs for this as my first task tomorrow morning.

If that looks okay, I'll then start on the 22.05 tasks.

David
Comment 7 Katrin Fischer 2022-06-21 11:24:48 UTC
Hi all,

+1 for the general idea, thx Martin for bringing this up!
+1 for having the RMaints set the status. Spread the burden is really key I think.

I am not sure about a 'documentation submitted' status - I think maybe posting a note with the gitlab merge request + setting to RESOLVED might suffice? Every click less is usually helpful.
Comment 8 Aude Charillon 2022-06-21 12:35:04 UTC
Thanks for looking into this! From my humble point of view as a Documentation beginner, it would make it a lot easier to find and manage what needs to be documented.
Comment 9 Martin Renvoize 2022-06-21 13:01:38 UTC
I've added a 'Documentation contact' customer field.. though it can't be linked to bugzilla users so we'll have to hope people just type their name in consistently (I was going to use it for the leaderboard sections of the dashboard if your interested and motivated by that sort of thing)

I've also re-enabled the 'Documentation submission' custom field which we introduced a while back but never really took off.. we could use that for gitlab merge request links.. but I'm not sure if that's adding burden to the process or is helpful?.. it could signify a submission has taken place in the bugzilla world to give us something to bind on for the dashboard again... jury's out.. let's see how this feels to start with.
Comment 10 Martin Renvoize 2022-06-21 13:04:41 UTC
(In reply to David Nind from comment #6)
> Thanks Martin for all your work on this!
> 
> I'll start reviewing and adding 22.11 bugs for this as my first task
> tomorrow morning.
> 
> If that looks okay, I'll then start on the 22.05 tasks.
> 
> David

Regarding back populating, perhaps we should work on a report or if you have a spreadsheet already, use that to do a bulk update? (With Chris disabling email to not spam the world too much)

I'm also wondering if we could just draw a line and work through old things via your existing sheets and use this workflow for moving forward?
Comment 11 Katrin Fischer 2022-06-21 14:54:17 UTC
A link field might be useful, but might be better linking to the section in the manual... but then you might have changed multiple pages. Not sure on that one yet.
Comment 12 David Nind 2022-06-21 19:51:53 UTC
(In reply to Martin Renvoize from comment #9)
> I've added a 'Documentation contact' customer field.. though it can't be
> linked to bugzilla users so we'll have to hope people just type their name
> in consistently (I was going to use it for the leaderboard sections of the
> dashboard if your interested and motivated by that sort of thing)

Hopefully, people can remember their names 8-), I'll make sure it is covered in the work flow instructions.

> I've also re-enabled the 'Documentation submission' custom field which we
> introduced a while back but never really took off.. we could use that for
> gitlab merge request links.. but I'm not sure if that's adding burden to the
> process or is helpful?.. it could signify a submission has taken place in
> the bugzilla world to give us something to bind on for the dashboard
> again... jury's out.. let's see how this feels to start with.

We can see how it goes. In the meantime, I'll add that to the work flow instructions as well.

Thanks Martin!
Comment 13 David Nind 2022-06-21 19:56:06 UTC
(In reply to Martin Renvoize from comment #10)
> Regarding back populating, perhaps we should work on a report or if you have
> a spreadsheet already, use that to do a bulk update? (With Chris disabling
> email to not spam the world too much)
> 
> I'm also wondering if we could just draw a line and work through old things
> via your existing sheets and use this workflow for moving forward?

It makes much more sense not to spam everyone, was thinking they might not appreciate all the email in their inbox!

I'll get my lists up to date for the current release, 22.05, 21.11 and 20.05, then we can look at.

Definitely, we should do for 22.11.
Comment 14 David Nind 2022-06-21 19:59:55 UTC
Thanks everyone for the feedback so far, and Martin for enabling things!

Current list of things to do:

- Get lists of documentation tasks up to date
- Look at bulk updating the current release
- Decide on whether to bulk update for previous releases
- Update work flow instructions
- Add to agenda for next development meeting
- Add to agenda for next documentation meeting
- Email to documentation and development mailing lists
Comment 15 Arthur Suzuki 2022-06-22 15:40:17 UTC
Just my 2 cents here.
Isn't the devs who provides code at the best place to know exactly what the code is doing or how it changes its behavior? and therefore documenting it?
Just like it is now mandatory to provides unit tests and test plans in the commit message, we could make a documentation mandatory for an enhancement or big change to reach Koha Community code.
Comment 16 Victor Grousset/tuxayo 2022-06-22 20:32:26 UTC
The topic came up on today's meeting.

Here is, like Arthur did, ideas about how to follow-up on the topic of documentation:

Maybe we could have a status "Failed QA, missing documentation" which the documentation team could also unblock taking the oldest ones first. So it does not get stuck forever on that.
But that still too much delay to get merged and can require rebases.

Another idea is to do it after the patch is merged to master. But it's the dev that does it and the documentation team if that takes too long. We can expect this to happen often since there isn't the incentive to have the patch merged anymore. But compared to the new workflow now from this ticket, it should cause part of the developers to do that and make less work for the documentation team. Would that work?
Comment 17 Victor Grousset/tuxayo 2022-06-23 01:55:06 UTC
Directly on topic for this ticket: we need in bugzilla to not be able to choose "push to oldoldstable" because the last RMaint should elect "Needs documenting", always.
Comment 18 Caroline Cyr La Rose 2022-06-23 12:36:41 UTC
(In reply to Victor Grousset/tuxayo from comment #17)
> Directly on topic for this ticket: we need in bugzilla to not be able to
> choose "push to oldoldstable" because the last RMaint should elect "Needs
> documenting", always.

I'm not sure that's true. We only document enhancements and new features afaik. We don't document bug fixes, which is usually what is backported to older versions.
Comment 19 Martin Renvoize 2022-06-23 13:34:09 UTC
I think the 'Needs documenting' tag serves as a list of all bugs that need an eye cast to make the decision as to whether to document or not.. your right, the majority of bugfixes will likely be a simple switch to 'Resolved Fixed' and thus very quick to remove from the queue (I've already done that to a couple in fact).

But there are some bugfixes with minor changes that affect functionality that I feel are worth updating documentation for.. so it's not a hard and fast rule.
Comment 20 Martin Renvoize 2022-06-23 14:33:52 UTC
Found a clear example for this.. bug 30599.. backported and does require some docs updates.
Comment 21 Martin Renvoize 2022-06-23 14:36:31 UTC
Jonathan has highlighted that this may create a bit of bugzilla spam as part of the process.. if every bug goes through this new state those of us that are cc on a metric tonne of bugs will get an email for the change to 'Resolved fixed'

I like that we're encouraging 'someone' to look at every bug and assess whether it needs a docs change or not.. but perhaps we could 'burden' the rmaints to be a little picky and do some of the obvious filterings at 'Not backporting' time.. when it's obviously a behind-the-scenes change that doesn't affect workflow, UX or UI they could just skip straight to Resolved Fixed still instead of using the middle 'Needs documenting' ?
Comment 22 David Nind 2022-06-23 19:40:37 UTC
(In reply to Martin Renvoize from comment #21)
> I like that we're encouraging 'someone' to look at every bug and assess
> whether it needs a docs change or not.. but perhaps we could 'burden' the
> rmaints to be a little picky and do some of the obvious filterings at 'Not
> backporting' time.. when it's obviously a behind-the-scenes change that
> doesn't affect workflow, UX or UI they could just skip straight to Resolved
> Fixed still instead of using the middle 'Needs documenting' ?

I think that would work - ideally, they should add a comment about why documentation updates are not required (as you have been doing),
Comment 23 David Nind 2022-06-23 20:06:52 UTC
Comments on comment #15 (Arthur) and comment #16 (Victor).

I think Martin has tried to encourage that type of work flow - where a bug isn't pushed until the docs are done, but that hasn't worked that well for Koha.

I'd more than welcome, and certainly encourage, contributions from developers for their bugs, but I realise that this may not necessarily be a strength or something they are interested in doing.

Everyone can contribute to the docs, but there is a bit of a learning curve (although developers are at least familiar with git, so that is once less hurdle!). I'll take a look at updating our instructions and guidance, which I'm trying to cover in a "Content Development Guide".

Slightly off-topic, but I'd probably like developers to focus on adding release notes before they tackle the documentation, for example:

- This new feature [does XYZ].
- This enhancement [adds X and Y to Z].
- This fixes [XYZ] so that it does [expected behaviour], [instead of whatever error or problem was happening]. 

That way, it makes it much easier to identify if documentation updates are required (instead of having to read through the bug history/latest patches).