FY23-Q1: Develop OKR Proposal: Troubleshooting docs epic
Mulling over how best to take on gitlab-org/gitlab#233141 (closed)
Ideas/comments welcome especially if you were involved in the previous docs OKRs, or related efforts
Notes from Previous docs OKR
From #2403 (closed)
- Use templates. Example issue: #2308 (closed)
- Multi-modal communication for encouraging messages and reminders: best though on issue directly
- Due date = reminder 2 days before. Should the due date be set early as a built-in reminder?
- Consider buddy/peer reviewer and/or working sessions to help move things along
- Previous template directed to look at tickets, but that was a "rabbit hole". Make sure to set clear expectations.
- Scope issues to be small to avoid result being a large MR
Consideration for OKR
From Craig in gitlab-org/gitlab#233141 (comment 844118695)
If this is something Support wants to take on, I'm thinking that both I and Diana can help coordinate. We'd want to be included in any epic created for this, as we'll want to get a sense of the amount of changes and the timeframe for the work. We need to balance this effort with the existing work for the TWs, based on our prioritization order.
From Arty
@lyle
☝ if we decide to take this on, we should think about whether it should be a joint OKR as we've done in the past (which Susan and Lee put together), or whether it'd be a Support-only OKR. I could see it being Support-only if the goal is to create MRs and not necessarily have them merged by the end of the same quarter (so as to not put pressure on the TW team on how quickly they need to be reviewed/merged)
From Lee
I'm partial to the "two phase" OKR where support targets making the MRs and TW can consume at their own pace which keeps us both unblocked. Less overhead, less management needed, and more async and encourages the Docs MR -> Publishing flow to get reinforced and made more robust.
OKR proposal
At GitLab we have a docs-first methodology. Support participates in that, as documented in How to respond to tickets - Ticket Deflection - Documentation.
As a part of our overall effort to deflect tickets and improve first response time, we want to ensure that our troubleshooting information is easy to find, and present where users are likely to see it.
The Technical Writing team has previously done research and has found that "proximity usually equals ease of discovery. If people are reading information about a feature and following instructions on how to use it, then having Troubleshooting info in close proximity is typically the way to go." Source
Additionally, moving the troubleshooting documentation assists in further implementation of the Documentation topic types (CTRT), which is often a Technical Writing OKR (FY23Q1 example), and allows Support Engineers to practice what they learnt in the Technical Writing Fundamentals course.
Resolves gitlab-org/gitlab#233141 (closed)
Would be tied to FY23 epic: &186
Calculation of OKR completion
Number of pages migrated
Steps / Actions required
For each set of pages
-
Content inventory refresh (last done 1 year ago) https://gitlab.com/groups/support/interns/-/epics/1 -
Create issues in the gitlab-org/gitlab
project with template description (below) https://gitlab.com/support/interns/documentation-inventory-project/-/issues/2 -
Post request for volunteers in Slack and SWIR -
Ensure all issues are assigned -
Consider complete when MRs are created
Side note: While not strictly part of the OKR, it would be a good idea to see what's left in the snippets project afterwards and resolve them.
Issue template
This assumes that we're looking at a section of a troubleshooting page, not the whole thing
Title: Move <heading> from <file name> to feature page
Link to specific heading: <insert link>
The listed section from our troubleshooting guide needs to be reviewed and moved.
1. [ ] Do a technical accuracy review.
- If the information is a duplicate or is to fix a bug that's no longer reproducible, consider whether it's still required. If we no longer need it, make a MR to remove the content instead.
1. [ ] If the content covers a rail command, look to see if there is an [open issue in the snippets project](https://gitlab.com/gitlab-com/support/toolbox/snippets/-/issues?sort=created_date&state=opened) that covers the same thing. Decide which version to keep, and close the snippets issue with a link to your docs issue.
1. [ ] Find the most appropriate (feature) page outside of the troubleshooting section of our docs to move the troubleshooting section to.
1. [ ] Double check if the information is duplicated. If partially duplicated, integrate the troubleshooting section to the content on feature page and ignore the next 2 steps.
1. [ ] If a troubleshooting section does not already exist at the bottom of the feature page, uncomment the heading (if present) or create it `## Troubleshooting [feature]`.
1. [ ] Move the content to the troubleshooting section on the feature page.
1. [ ] Ensure the heading for your content includes "in Rails console" and the first line after the header includes a link to how to `[start a rails console session](../administration/operations/rails_console.md#starting-a-rails-console-session)`.
1. [ ] Ensure the content follows the [the troubleshooting content/structure style](https://docs.gitlab.com/ee/development/documentation/structure.html#troubleshooting). If you have style guide questions, feel free to ask in the #docs Slack channel or submit the MR and make comments for the Technical Writer to review.
1. [ ] Create a MR with the changes and follow the usual process for review/assignment.
/epic &8147
/label ~documentation ~"good for new contributors" ~"type::maintenance" ~"docs::improvement"