Q4 OKR: Provide improved documentation experience for the top 10 Jobs to be Done (JTBD) by improving discovery and making content more relevant and usable => 100%
Review and improve the doc experience around 10 Experience Baseline (now renamed to UX Scorecard) JTBDs, continuing on the work started in &1678 (closed).
About UX Scorecards: https://about.gitlab.com/handbook/engineering/ux/ux-scorecards/
Requirements for Each Selected JTBD
- Review existing info - Review the UX issues, walkthrough video, and recommendations. If you have any questions, ask the Product Designer who performed the experience baseline review for your JTBD.
-
Review SEO - Review the experience as a user searching for how to perform the JTBD, both on Google (for meaningful docs.gitlab.com results) and on the doc site's search. Determine whether relevant pages and meaningful titles/subheadings exist so that the search is successful, or any content improvements that would help with the search.
- Document and improve SEO - Specify one or more search queries that a user would use for this JTBD, their current result via Google and Algolia, a grading of the current result, and a final result after changes are made to the section.*
- Consider potential UI doc link - Determine if any aspect of the JTBD experience (per the UX review) could be enhanced by linking from the UI to the most relevant, contextual documentation content, and collaborate with the Product Designer to implement this.*
-
Review and improve documentation content - Ensure the relevant docs content is clear on what's possible in GitLab related to the JTBD, and how to go about it.
- Test the instructions (to the extent they were not yet tested in the experience baseline review) and identify new content or improvements that are needed. Specifically, determine if any content is unclear, inaccessible to new users (e.g. using technical terms without defining/linking), includes incorrect or outdated information or screenshots, contains any gaps or missing information, is difficult to navigate due to headings or structure, or otherwise has an issue that may impede the user's ability to accomplish the JTBD.
- Based on the findings, plan documentation improvements/additions; include any documentation recommendations from the UX issue, and further, this may include: improvements to ensure clarity, conceptual accessibility to new users e.g. backlinks to more fundamental concepts, fix outdated screenshots, reorganize information for improved use/browsing, or resolve any process/content gaps or errors. Work with SMEs from the stage group as needed, and determine best content reviewer(s) from Product, Engineering, or UX, depending on the content.
- Ask questions of and share plans with the Product Designer, for review.
- Implement doc changes and share for review(s).
* Improvements in search results and UI-based doc links may need to wait until documentation improvements are made, per item 3.
Current JTBDs Identified
| Stage | Tech Writer | Job to be Done (JTBD) | Q2 UX Experience Score | TW issue or MR | UX Evaluation issue | UX recommendations issue | Clarity of doc needs | Potential doc OKR work | Notes re doc OKR |
|---|---|---|---|---|---|---|---|---|---|
| Configure | @eread | Add my existing Kubernetes cluster | C- | gitlab#30575 (closed) | #487 (closed) | &1382 (closed) | Document prerequisites. | Continuation of OKR work from last quarter, now that EKS clusters have new functionality added. Specifically, addressing concerns around having all pre-requisites in place before following documentation. | |
| Manage | @eread | Transitioning from self-managed to Gitlab.com | - | gitlab!24130 (merged) | - | - | Improve project import/export documentation. | Documentation structure and conventions are of a low standard. Raise level of quality. | |
| Create | @marcel.amirault | Create a merge request (Approval rules & Changing branches) | D | gitlab#42651 (closed) | #441 (closed) | #444 (closed) | MR Approvals docs really hard to understand. | Needed complete revamp to all sections, move unrelated sections to correct pages, more crosslinking. | See MR |
| Create | @marcia | How to create an MR | C | gitlab#39523 (closed) | #441 (closed) | #444 (closed) | gitlab!21956 (merged) | ||
| Growth | @rdickenson | Start a GitLab trial | D- | gitlab#37736 (closed) | gitlab-org/growth/product#166 (closed) | gitlab-org/growth/product#180 (closed) | TBD | TBD | TBD |
| Plan/Create | @marcel.amirault | Create a Merge Request (Template, Labels, Milestones, Assignees) | C | gitlab#199399 (closed) | #441 (closed) | #444 (closed) | For Label/Milestones, label doc was the worst. | Far too many large images, too reliant on images. Needed more details, clearer examples, and better text instructions to avoid the images. | OKR was for Create, but "Labels" is Plan, so added labels to match, and pinged Plan designer. |
| Plan | @rdickenson | Receive and configure Issue notifications and To Dos | D+ | gitlab#37738 (closed) | #450 (closed) | #520 (closed) | TBD | Continuation of docs improvements identified in Q3 UX OKR item on the same topic. | TBD |
| Plan | @rdickenson | Understand dependencies as they relate to a larger scope | C+ | gitlab#37739 (closed) | #449 (closed) | #497 (closed) | TBD | TBD | TBD |
| Release | @msedlakjakubowski | Create a Release and update it | F | gitlab#31711 (closed) | #431 (closed) | #505 (closed) | TBD | Flesh out our releases page to show the current state of the feature; how to manage a release using the current features. | 1. Improve UI text in the empty-state Releases page, following UX recommendations. 2. Update Releases documentation to reflect the correct ways of creating a Release, not just through the API. |
| Package | @axil | Package: Research Specific Image | D | gitlab!23901 (merged) | - | - |
To Do
-
@eread: Look at the JTBD UX Scorecards spreadsheet and select 10 workflows to improve the docs for. -
@eread: Add the workflows to the table above. -
@eread: Assign to writers on the team, based, where possible, on their stage/group assignments and if it's further work on an area covered in Q3, then keeping the TW consistent. (2 issues per tech writer who was on the team before October, 1 per tech writer who onboards by end of December.) -
@eread: Work with writers to get an issue created for each workflow using the format of issues linked from the similar Q3 epic &1678 (closed). -
@eread: Encourage tech writers to communicate with the relevant Product Designer immediately so that collaboration can kick off without unnecessary delay.
Edited by Mike Lewis