End-to-end QA

Before launch, but after development work is done, we should re-test everything to check for regressions.

A regression is something that works on the Nanoc site, but does not work on the Hugo site, or anything that looks broken.

Note: at this partially-launched time, there are a few things on https://new.docs.gitlab.com that won't be quite right:

Website features

Everyone in Technical Writing should take a few minutes to review an assortment of pages on https://new.docs.gitlab.com/ for the docs they are DRIs for. Especially pages they know to have edge cases, like irregular content, formatting, tables, etc. We should all double check that:

  • Search works as well as the old site.
  • Links to files from the "Help and Feedback" section (blue section at the bottom of every docs page) work. Especially the "Edit this page" link.
  • Left navigation expands, collapses, and otherwise works as expected.
  • Right nav renders correctly, matching the sections on the page.
  • Tables render correctly:
    • Large tables do not stretch outside the view.
    • Tables never overlap other content.
    • Headers and other special characters (like <sup> and <br>) continue to work as expected in tables.
  • Badges render correctly in all variations.
  • NOTE:, WARNING: and other note blocks render as expected.
  • History items render correctly in all variations:
    • Single items (unexpanded)
    • Multiple items (expanded)
  • Diagrams render as expected (Mermaid samples, plantUML samples)
  • Page titles and section headers (H2, H3, etc) render as expected, including when special characters or formatting are included like backtick content. Page titles should also render in browser tabs.
  • Deprecations page "Filter by removal version" feature works as expected: https://new.docs.gitlab.com/update/deprecations/
  • Special formatting and characters render as expected:
    • Codeblocks render as expected, with code coloring.
    • SVGs display correctly, with appropriate size and spacing.
    • Pages that use HTML for special formatting render as expected.
Plain markdown list for copy/pasting 
- [ ] Search works as well as the old site.
- [ ] Links to files from the "Help and Feedback" section (blue section at the bottom of every docs page) work. Especially the "Edit this page" link.
- [ ] Left navigation expands, collapses, and otherwise works as expected.
- [ ] Right nav renders correctly, matching the sections on the page.
- [ ] Tables render correctly:
  - [ ] Large tables do not stretch outside the view.
  - [ ] Tables never overlap other content.
  - [ ] Headers and other special characters (like `<sup>` and `<br>`) continue to work as expected in tables.
- [ ] Badges render correctly in all variations.
- [ ] `NOTE:`, `WARNING:` and other note blocks render as expected.
- [ ] History items render correctly in all variations:
  - [ ] Single items (unexpanded)
  - [ ] Multiple items (expanded)
- [ ] Diagrams render as expected ([Mermaid samples](https://new.docs.gitlab.com/development/geo/proxying/#request-lifecycle), [plantUML samples](https://docs.gitlab.com/ee/development/database/batched_background_migrations.html#execution-mechanism))
- [ ] Page titles and section headers (H2, H3, etc) render as expected, including when special characters or formatting are included like backtick content. Page titles should also render in browser tabs.
- [ ] Deprecations page "Filter by removal version" feature works as expected: https://new.docs.gitlab.com/update/deprecations/
- [ ] Special formatting and characters render as expected:
  - [ ] Codeblocks render as expected, with code coloring.
  - [ ] SVGs display correctly, with appropriate size and spacing.
  - [ ] Pages that use HTML for special formatting render as expected.

Post launch

Only need to be checked by folks actively working on the rollout:

  • Review the GLFM page to see if everything that should be working is still working (many things are not expected to work outside of /help or raw markdown views on a GitLab instance).
  • Hugo short codes and other special characters are hidden
  • Redirects work, automatically forwarding to correct page.

Authoring experience

Only need to be checked by folks actively working on the rollout:

  • Review apps work in all upstream projects, as well as this project:
    • gitlab-org/gitlab
    • gitlab-org/gitlab-runner
    • gitlab-org/omnibus-gitlab
    • gitlab-org/charts/gitlab
    • gitlab-org/cloud-native/gitlab-operator
    • gitlab-org/technical-writing/docs-gitlab-com
  • Review app links within MRs point to correct URLs.
  • Issue and MR templates up-to-date for this project, including left navigation updates.
  • ...

Archive features

Only need to be checked by folks actively working on the rollout:

  • Version appears in the dropdown of the homepage
  • Search works
  • Banner This is archived documentation for GitLab. Go to the latest. appears at the top of the pages

Scripts and tools

Only need to be checked by folks actively working on the rollout:

  • (Post-launch) Monthly chores updated to work with new site.
  • Pipeline runs rendering tests before deploy is possible, to prevent broken deployments.
  • Markdownlint and Vale give similar results, properly ignoring Hugo shortcodes and similar.
  • ...
Edited by Sarah German