Skip to content

Full copy edit of latest changes to ci components and catalog docs

Marcel Amirault requested to merge docs-ci-component-description into master

What does this MR do?

There have been a fair amount of changes to the CI/CD components and Catalog pages from multiple authors and reviewers over the last few months. Additionally, some folks have pointed out some confusing sections on the page, so this important and rapidly evolving feature's docs is in need of a major copy edit.

This MR cleans up a significant portion of the two docs, including:

  • Shortening long lines.
  • Simplifying language.
  • Changing examples to make them easier to understand, or to better highlight the relevant details.
  • Other standard "TW" copy edit fixes to improve the language and make all the recent edits work better together.

Some of the bigger changes are to the Best Practices section, including moving the component testing section to there for now. Where it was placed in the middle of the page was interrupting the main flow which was trying to explain how components work and are used. Testing is a good recommendation, but not required and not needed at the current spot in the page.

It also:

  • Resolves the linked issue by adding a note about project descriptions.
  • Incorporates the changes in !129827 (merged) into this MR to make all the changes at once and save us the merge conflicts.

Related issues

Author's checklist

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 like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure 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.
Edited by Marcel Amirault

Merge request reports