Add site-specific conventions linting to the Web IDE.
Problem to solve
Our marketing site, including both the Blog and the Handbook, is full of small issues that are repeatedly added and left in place until they are noticed and fixed. Discovery can take a long time and fixing and testing can cost a lot of time. These issues include but are not necessarily limited to the following:
- bad link URLs - not just unreachable, but improperly formatted
- valid link URLs that do not follow site conventions - e.g., absolute URLs, which prevent instance-specific testing
- new-content URLs that do not follow site conventions - e.g., uppercase or mixed case instead of lowercase and encoded spaces or underscores instead of hyphens
- bad headings - e.g., level 1, ALL CAPS, sentence case where title case is preferred, title case where sentence case is preferred, including superfluous boldness Markdown, or including nested links
- whitespace - too many spaces, too many lines, too few, and spaces vs. tabs
- common spelling and capitalization errors
Intended users
Everyone who uses the Web IDE.
Further details
Although conventions are listed in the Handbook, the Handbook is is enormous, so realistically, nobody can know and remember everything in it. Individual contributors don't remember every convention when they add and edit content and even managers and other maintainers do not remember every convention when they accept merge requests.
Proposal
Detecting and flagging such issues at edit time would reduce the introduction of new issues (whether or not detected in pipelines), encourage fixes to existing issues, and help contributors develop good habits, so we should implement such detection and flagging in the Web IDE.
Permissions and Security
To Be Determined
Documentation
To Be Determined
Testing
To Be Determined - However, this change would increase the quality of content managed through GitLab.
What does success look like, and how can we measure that?
The issues listed above are all detected in the Web IDE.
What is the type of buyer?
Not Applicable - This is mainly for GitLab's own marketing site, especially our very frequently edited Handbook.