Q3FY22 KR: Improve product learnability by structuring docs for better discoverability
Refactoring existing docs pages to follow the CTRT content format will begin to improve the organization and learnability of GitLab documentation.
Tech writers, please select one page from your areas of responsibility, and ASSIGN @sselhorn AS REVIEWER.
Choose a page to work on:
- Consider the content audit. You might want to pick a popular page in your area. Use the score and page views to determine popularity. If you want to sort the spreadsheet, make a copy first. Otherwise it will fail. There is an existing column that shows if a page has already been edited for CTRT.
- Some pages are longer than others. You'll only be working on one page, so consider how many topics (a chunk of information with a heading) you think you can complete in a quarter. You might want to open one MR per topic or for a few topics at a time.
- 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 under Page assignments. 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
cd
until you're in the directory with the file, then runvale <filename>.md
. The score should be displayed.
The idea is to start practicing CTRT as a team, not to update the whole docset or to achieve 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
@sselhorn
for 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
Tech writer | Page Link | Readability score before | After |
---|---|---|---|
Amy | Repository mirroring | 12.19 | 11.19 (page was split into 4) |
Axil | Omnibus update | 13.19 | 12.32 |
Evan | General LDAP setup | 12.72 | Page split as part of work. New score for that page (9.95). |
Fiona | Snowplow Guide | 11.03 | 13.20 (This page was split into multiple pages, causing the number to go up) |
Kati | Webhooks integration | 10.22 | 9.41 |
Marcel | GitLab CI/CD include examples | 14.16 | 9.88 |
Marcia | Kubernentes Agent | 11.95 | 11.59 |
Marcin | GitLab Notification Emails | 12.24 | 12.09 |
Nick | Package Registry | 9.65 | |
Russell | Coverage Guided Fuzz Testing On hold | 10.62 | |
Russell | CVE ID Requests | 13.09 | 11.81 |
Progress
- Amy
-
Chose a page -
Began opening MRs -
Completed
-
- Axil
-
Chose a page -
Began opening MRs -
Completed
-
- Evan
-
Chose a page -
Began opening MRs -
Completed
-
- Fiona
-
Chose a page -
Began opening MRs -
Completed
-
- Kati
-
Chose a page -
Began opening MRs -
Completed
-
- Marcel
-
Chose a page -
Began opening MRs -
Completed
-
- Marcia
-
Chose a page -
Began opening MRs -
Completed
-
- Marcin
-
Chose a page -
Began opening MRs -
Completed
-
- Nick
-
Chose a page -
Began opening MRs -
Completed
-
- Russell
-
Chose a page -
Began opening MRs -
Completed
-
Edited by Suzanne Selhorn