FY24Q3 TW OKR: Refactor high visibility pages for improved content design and better scannability => 71%
Refactoring existing docs pages to follow the CTRT content format will improve the findability, organization, and learnability of GitLab documentation.
Technical writers will refactor two pages of content in their respective areas of responsibility.
Focus area
We are focused on the Use GitLab
area of the docs, because it accounts for 67% of the page views on docs.gitlab.com.
We have completed 262 of 577 pages so far for the Use GitLab
area of the docs (45%). If we complete all the pages in this KR, we will have completed 278 of 577 pages. We frequently add more pages to the docs, so we expect these numbers to fluctuate over time. Therefore, these numbers are for tracking purposes only, and do not represent a growing target for reviewed pages.
Directions for writers
Choose a page to work on
View your personal tab in this spreadsheet. It shows your most popular topics. Column G indicates if the page is already done, however it's possible that this column is out of date.
Choose a page that meets the following criteria:
- Page has a significant view rate.
- Page has content that can be refactored into the CTRT format.
- Page hasn't already been refactored into the CTRT format.
- Page is in the
Use Gitlab
area of the left nav.- You might own very few
Use GitLab
pages, but do own other pages that account for high views on our docs site. These pages can also be refactored for CTRT if they are important for our users.
- You might own very few
After you choose a page
- Update the table to include the page name and the readability score. The easiest way to get the score is to
cd
until you're in the directory with the file, then runvale <filename>.md | grep gitlab.ReadingLevel
.
Make edits to the page
- Make sure the page follows the CTRT topic types.
- You might need to combine topics or re-order content. You can open as many MRs as you'd like/you need.
- New this quarter: When working on the concept section of your page, pay special attention to the What and Why of the feature. If this information is missing, work with an SME to add it.
- Review the search terms for the page by updating the page in this string:
https://search.google.com/u/1/search-console/performance/search-analytics?resource_id=https://docs.gitlab.com/&breakdown=query&page=!https://docs.gitlab.com/ee/user/project/issues/design_management.html
- Ensure any notes or warnings on the page are absolutely necessary.
- Pay attention to the right nav. When you're done with the full page, it should be easy to scan. If you open multiple MRs over time, this can be a final step.
- When ready, open an MR and in the description, add this issue as related.
- Assign your MR to Suzanne, Kati, Fiona, or Diana for review as follows:
- Suzanne: Amy, Marcel, Lysanne
- Diana: Phillip, Jon
- Kati: Russell, Fiona
- Fiona: Lorena, Marcin
- When the page is complete, check your name off the list.
Page assignments
- Amy
-
Page 1 complete -
Page 2 complete
-
- Fiona
-
Page 1 completeRe-assigned to support https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/4135 -
Page 2 completeRe-assigned to support https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/4135
-
- Lorena
-
Page 1 completeRe-assigned to support https://gitlab.com/gitlab-com/gl-infra/gitlab-dedicated/team/-/issues/2828 -
Page 2 complete
-
- Lysanne
-
Page 1 complete
-
- Jon
-
Page 1 complete -
Page 2 complete
-
- Marcel
-
Page 1 completeRe-assigned to support https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/4135 -
Page 2 completeRe-assigned to support https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/4135
-
- Marcin
-
Page 1 complete -
Page 2 complete
-
- Phillip
-
Page 1 complete. -
Page 2 completeRe-assigned to support https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/4135
-
- Russell
-
Page 1 complete -
Page 2 complete
-