Feedback: new.docs.gitlab.com alpha release
Earlier this week, we posted a preview version of the GitLab Docs Hugo website here: https://new.docs.gitlab.com
At this time, we'd like the Technical Writing team to take a look around the site, and let us know if you spot any issues. We'll do a follow-up release shortly afterwards to request feedback from the broader GitLab team and community contributors.
It'd be especially helpful if each Technical Writer could look over their most high-traffic pages.
You can use this spreadsheet to see your highest-traffic pages, but note that our data is from the May 2024 content audit, so newer pages are not included here. You may want to give those a look as well if they're high-profile (e.g, GitLab Duo pages). The spreadsheet includes a link to both the Nanoc and Hugo versions of the page.
Optionally, try running a local site and let us know if you run into any problems via an issue, or a ping in the #docs-tooling Slack channel.
What to look out for
- Malformed content
- Example: unrendered markdown on the deprecations page (Issue)
- Visual/layout bugs
- Examples: Overlapping content or page regions, content that looks significantly different than the current site, problematic inconsistencies between our supported web browsers
- Issues with custom elements (tabs, alert boxes, anything else that is now a shortcode) that we've programmatically migrated to the new Hugo format.
- Issues with "unusual pages," such as automated pages
- Broken links within the site. We are still working on redirect handling to reflect the URL changes for Hugo, but all links from the global navigation or within the regular content should work.
Known issues
- All open bugs
- "Edit this page" and "View in webIDE" links will not work for
index.mdfiles until we actually update the source files (#82 (closed)) - Minor visual bugs on mobile. Feel free to add anything to (#97 (closed)), but given our very low traffic on non-desktop devices, these will be very low-priority.
- Blockquotes are unstyled (see #94 (comment 2016222519))
- Table in GitLab documentation does not do well ... (gitlab-org/gitlab-docs#952 - closed) • Sarah German
- Some pages will contain Kramdown tags until we resolve #76 (closed)
- There are a few minor design changes to reflect more updated Pajamas styles or a change to a new tool (e.g, the menu looks a little different, clipboard copy looks a little different, ToC behaves a little differently). In theory these are good changes, but let us know if you think anything is harder to use.
User-facing features that not yet implemented
- Add 404 page (#92 - closed) • Hiru Fernando
- Version-specific behavior (https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/versions.md?ref_type=heads)
- Feature flags list (#17 (closed))
- Content changes related to the Hugo project (e.g, updating the style guide to reflect markdown changes)
Out of scope for this project
- Significant visual design changes
- Localization
Next steps in the project
We'll continue working through this epic. This includes:
- Accessibility review: #41 (closed)
- Spike: Test alternative redirect strategies (#96 - closed) • Sarah German
- Rename index files and update page titles on st... (#82 - closed) • Evan Read, Marcel Amirault • 17.9
- How can we make Hugo-specific markup presentabl... (#56 - closed) • Sarah German
- Tools we use for releases and maintenance (rake tasks)
- Version-related features (for example, offline search, Docker images for Archives)
- Support for various local setups (GDK, GitPod, GitLab Workspaces)
- Training/reference material for TWs and contributors (e.g, how to use shortcodes)
-
Launch planning and launch
🚀