Q4FY22 OKR: 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.
One page has been selected for you on the following basis:
- 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
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/1TPu0OTBLr7u8qco8T9bAl33r21bfnA4KvFyMElsU9AA/edit?usp=sharing
Tech writers, please select two pages from your areas of responsibility, and ASSIGN @sselhorn AS REVIEWER.
Choose a page to work on:
- Some pages are longer than others.
- Consider a page that has old screenshots that you can remove or retake.
- Find something messy that you're excited to clean up.
- If you need inspiration/ideas, this handbook page of examples might help.
When you've chosen a page:
- Add a link to your page in the table. Don't worry, if you assign yourself a page and realize you've made a horrible mistake you can always change course.
- Run Vale to get the readability score and add that to the table as well. The easiest way to get the score is to
cduntil you're in the directory with the file, then runvale <filename>.md | grep gitlab.ReadingLevel. The score should be displayed.
The idea is to practice CTRT as a team and to start making changes across the docset. In the GitLab way, we will make progress but not worry about perfection.
Make edits to the page:
- Refer to the topic types for reference.
- For each topic on the page, edit it to ensure the format is an obvious topic type. You might need to combine topics or re-order content. You can open as many MRs as you'd like/you need.
- 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
@sselhornfor review/merge. In the description, add this issue as related. - When the page is complete, check your name off the list below. (The Ally tool uses checkboxes to track status.)
Page assignments
Progress
- Amy
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Axil
-
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
-
- Kati
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Marcel
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Marcia
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Marcin
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-
- Nick
-
Page 1 complete -
Page 2 complete -
Page 3 complete
-