FY23Q4 TW OKR: Refactor high visibility pages for improved content design and better scannability => 83%
Refactoring existing docs pages to follow the CTRT content format will improve the findability, organization, and learnability of GitLab documentation.
Technical writers will refactor one page of content in their respective areas of responsibility. Assign all MRs to @dianalogan
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 245 of 468 pages so far (52%).
- If we complete all of the pages in this OKR, we will be at 257 of 468, or 54%.
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): https://docs.google.com/spreadsheets/d/1eh06M1t_BTnaEqhkQjtpNRfYOeJ6Ub_qU08hCVWmlZc/edit?usp=sharing
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
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
- 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
@dianalogan
for review/merge. In the description, add this issue as related. - When the page is complete, check your name off the list.
Page assignments
- Amy
-
Page 1 complete
-
- Ashraf
-
Page 1 complete
-
- Axil
-
Page 1 complete
-
- Clayton
-
Page 1 complete
-
- Evan
-
Page 1 complete
-
- Fiona
-
Page 1 complete
-
- Lorena
-
Page 1 complete
-
- Jon
-
Page 1 complete
-
- Marcel
-
Page 1 complete
-
- Marcin
-
Page 1 complete
-
- Phillip
-
Page 1 complete
-
- Russell
-
Page 1 complete
-
Edited by Fiona Neill