Hand over Jira integration cleanup work
Problem to solve
This issue is intended to collect the various issues and merge requests that have come in about the Jira integration documentation so @kpaizee has a SSOT to start from. Before diving in, Kati should talk to @dianalogan or @cnorris about prioritization - this work is not included in the point totals for engineering feature work slated for %14.1. Let's ensure she doesn't get swamped like I did.
(Multiple issues / merge requests with high point values have been assigned to me in the last 4 milestones, and I am not able to do high point value / complex cleanup work AND keep up with feature work.)
Further details
Previously, our Jira integration page was two long, confusing pages that described several different integrations all jumbled together. It took multiple MRs to split them apart, !58807 (merged) being the last of them. I left a note in that merge request !58807 (comment 550965350) saying I didn't have a great deal of confidence in certain portions of my split work:
We need to check the in-page cross-links in a follow-up issue. There are various points in each integration's page where we try to crosslink to installing / configuring either Jira or GitLab, and I couldn't figure out what to cross-link where. I made guesses. They're probably wrong.
Our "Jira integration" is actually multiple different integrations, which provide overlapping feature sets, which makes untangling it harder.
Proposal
- Start by giving @kpaizee a work-appropriate hug, because wow, this is a lot. I knew, intellectually, it was. However, pulling out issue after issue after issue was disheartening, AND also reminded me of why I couldn't finish up this work. It needs contiguous time for deep thought.
- Ensure Kati gets a basic familiarity with what each of the Jira integrations can and can't do.
- Kati to assign the open issues to herself, and prioritize each of them based on discussions with Diana / Craig.
- Kati to review the issues referenced here, yell loudly at Amy, and to start devising a plan. #327646 (closed), plus the feedback issues, likely point to where the problems lie.
- Kati to get engineering time, as needed, to help ensure the right info lands on the right pages.
Who can address the issue
@kpaizee and @aqualls, with help from engineers in ~"group::ecosystem".
Other links/references
First, the identification of the problem:
- Related to #300312 (closed) where Suzanne identified the Jira pages as needing CTRT work.
- Related to #323644 (closed) where the PM had simultaneously identified to Amy that the Jira pages needed the most urgent work
- Related to #324965 (closed) (Revise ./user/project/integrations/jira.md for Ecosystem) where Amy initially thought all the work could be contained. This issue doesn't really provide value any more, and should probably close.
- Related to #324250 (closed) (Create plan to combine Jira pages)
- Contains the 14 MRs needed to gradually split these pages apart, and move them
Issues filed before the cleanup started, which the cleanup hoped to address:
- Related to #268278 (closed) (Document Usage of Jira Connect application with Self-hosted GitLab)
- Related to #209903 (closed) (Jira Server integration documentation is not complete) This references https://docs.gitlab.com/ee/user/project/integrations/jira_server_configuration.html
TW-identified aftermath of work:
- Related to #327646 (closed) (Follow-up from "Jira integration: final split of docs")
- This issue contains good information from
@toupeira
that may provide a blueprint for how to move forward
- This issue contains good information from
- Related to #327784 (closed) (Clean up new Jira pages)
Feedback from users and coworkers about problems, post-migration:
- Related to #333394 (closed) (Docs feedback: Jira Integration Articles not accurate)
- Related to #330017 (closed) (Create standalone Jira installation section) with items Craig identified
- Related to gitlab-org/growth/team-tasks#352 (closed) (Update Jira DVCS docs from Atlassian info) where a Growth team member identified some likely needed text updates
- Related to #335133 (closed) (Docs feedback: Jira integrations docs confusing) already assigned to Kati
Older issues that can probably be dealt with as part of the finishing up:
- Related to #297374 (closed) (Docs feedback: JIRA DVCS explain where to expect commits to be shown)
- Related to #294274 (closed) (Add user documentation for JiraConnect app)
- Related to #214090 (closed) (Docs feedback: the Services API for Jira does not mention the api key)
- Related to #209903 (closed) (Jira Server integration documentation is not complete)