[Koha-bugs] [Bug 30998] [DOCS] Managing documentation tasks - simplify processes and integrate more with the development process

[bugzilla-daemon at bugs.koha-community.org]

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998

--- Comment #3 from Martin Renvoize <martin.renvoize at ptfs-europe.com> ---
(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.

-- 
You are receiving this mail because:
You are watching all bug changes.