Reduce number of accumulated "Notes" throughout docs
Issue Description
Over time (for many reasons), the number of uses of the Notes alert in our docs has risen to levels that require attention.
From a review on Sep 22, we have 1,656 instances where NOTE: is in use in the docs, across 573 doc pages (including GitLab, Charts, Omnibus, and Runner). This means we have 57% of our doc pages with at least one Note.
Of the 573 pages with a Note, 251 of them have only a single Note, but 85 of them have 5 or more Notes (with one page having 40). Here's a table of the pages with 10 or more Notes:
Goal
To ensure that notes draw attention to the information they contain, we should reduce our use of notes in the published docs by 25%. This would bring the number down from 1,656 to 1,242, or from 573 to 430 pages. These are not hard rules, but goals, knowing that notes should be used only when they're truly necessary.
Actions
-
@cnorris: Review Notes guidelines in the Documentation Style Guide to encourage better usage of Notes in the future. Issue/MR: gitlab!43066 (merged) -
Team: Review your product docs to ensure that Notes are being used appropriately and sparingly, for best effect. Use this Google sheet to help you identify pages for updating. Create tracking issues/MRs as needed for your work, and select the check box for your name when you're done reviewing your pages.
Noting @clenneville and @susantacker for awareness.