Clarify language around deprecations and removals
What does this MR do?
In !107457 (merged), we updated the language in the deprecation/removal templates to focus less on the "deprecation" and "removal" terminology. That made it clearer that these entries could be other types of announcements that are not deprecations or removals. We also have changing defaults, added/changed limits, updated CI/CD templates, and other behavior changes that we need to announce, usually due to being a breaking change.
We should align the language in the main page as well, because we end up with sections like this:
## Removed in 15.4
### SAST analyzer consolidation and CI/CD template changes
## Removed in 15.0
### API: `stale` status returned instead of `offline` or `not_connected`
I don't believe it's accurate to say "Removed in" for these "non-removal" breaking changes. But if we change to Changed in 15.4
, it'll work for all types of announcements on this page.
This is similar to the language update in Pared down language and added Announced in (!88476 - merged), where we started using Announced in
for the deprecations, which also works for all types of announcements.
I've also updated the intro sections for both pages to reflect the nature of the content on the pages.
SEO
A separate issue is that if you are interested in upgrading and searching the site for a breaking changes list, the search term breaking changes
does not list this page in the first results:
If you scroll down and eventually find the page, it's not clear that this is the correct page. Is the "removals" page the one that lists the breaking changes?
Adding Breaking changes
to the title (# Removals and breaking changes by version
) should help with the SEO issue and make sure people are landing on the correct page. I think this is important to do now, before 16.0, as we'll have a flood of people looking for these details when 16.0 is released.
Review apps
- https://main-ee-114395.docs.gitlab-review.app/ee/update/deprecations.html
- https://main-ee-114395.docs.gitlab-review.app/ee/update/removals.html
Related issues
- Resolves gitlab-com/www-gitlab-com#14106 (closed)
- Related to !107457 (merged)
Author's checklist
-
Optional. Consider taking the GitLab Technical Writing Fundamentals course. -
Follow the: -
If you're adding or changing the main heading of the page (H1), ensure that the product tier badge is added. -
If you are a GitLab team member, request a review based on: - The documentation page's metadata.
- The associated Technical Writer.
If you are a GitLab team member and only adding documentation, do not add any of the following labels:
~"frontend"
~"backend"
~"type::bug"
~"database"
These labels cause the MR to be added to code verification QA issues.
Reviewer's checklist
Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.
If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.
-
If the content requires it, ensure the information is reviewed by a subject matter expert. - Technical writer review items:
-
Ensure docs metadata is present and up-to-date. -
Ensure the appropriate labels are added to this MR. -
Ensure a release milestone is set. - If relevant to this MR, ensure content topic type principles are in use, including:
-
The headings should be something you'd do a Google search for. Instead of Default behavior
, say something likeDefault behavior when you close an issue
. -
The headings (other than the page title) should be active. Instead of Configuring GDK
, say something likeConfigure GDK
. -
Any task steps should be written as a numbered list. - If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
-
-
-
Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.