Q3FY23 KR: Improve findability, organization, and learnability of GitLab content by refactoring docs pages
Refactoring existing docs pages to follow the CTRT content format will improve the findability, organization, and learnability of GitLab documentation.
Technical writers will refactor three pages of content in their respective areas of responsibility. Assign all MRs to @kpaizee
for review.
Focus area
- We are focused on the
Use GitLab
area of the docs, because it accounts for 63% of the page views on docs.gitlab.com.
Note that Axil owns very few "Use GitLab" pages.
- We have completed 161 of 420 pages so far (38%).
- If we complete all of the pages in this OKR, we will be at 187 of 420, or 44%.
Directions for writers
One page has been selected for you
- 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
Choose two other pages to work on
- View your personal tab in this spreadsheet. It shows your most popular topics (blue highlight indicates that the page is already done): https://docs.google.com/spreadsheets/d/1dVTCnEDL5m61ibMhHzBMsgD7tRWYgp73Hk30QtA3Trw/edit?usp=sharing
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
-
New this quarter! 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
- Refer to the topic types for reference.
- Ensure the type for each topic is obvious. You might need to combine topics or re-order content. You can open as many MRs as you'd like/you need.
- 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. (As can editing the intro at the top of the page, which is usually a concept.)
- When ready, open an MR and assign to
@kpaizee
for review/merge. In the description, add this issue as related. - When the page is complete, check your name off the list. (The Ally tool uses checkboxes to track status.)
Page assignments
- Amy
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Ashraf
-
Page 1 complete -
Page 2 complete
-
- Axil
-
Page 1 complete
-
- Clayton
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Evan
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Fiona
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Lorena
-
Page 1 complete -
Page 2 complete
-
- Marcel
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Marcin
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Phillip
-
Page 1 complete
-
- Russell
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
Edited by Marcin Sedlak-Jakubowski