[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 #2 from David Nind <david at davidnind.com> ---
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.

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