Skip to content

Update style guide to use "in" instead of "on" for UI element locations

Summary

Update the recommended word list to standardize on using "in" instead of "on" when referring to UI elements and locations within the GitLab interface.

Background

During review of MR !209632 (merged), inconsistencies were identified in our documentation regarding the use of "on" vs "in" when describing UI element locations. Our current word list guidance recommends using "on" as a preposition for high-level UI elements, following Microsoft's style guide.

However, after discussion with @fneill, @ashrafkhamis, and @kpaizee, there's consensus that "in" is more logical and aligns better with how users mentally model interfaces. Users interact with elements in the GitLab application, not on it.

Additional feedback

From @msedlakjakubowski:

I think our general guidance works for the panels too. Though, as this thread shows, we should clarify it.

If we followed proper English grammar as much as possible, we'd use:

  • "in" for [upper-/lower-/right/left] corner
  • "on ... page" - this is what you would say for a paper page, so it makes sense to stay consistent to match users' mental models
  • "on" when a container can be seen as a surface: like "area", "section", or "panel".
  • "in" when a container can be seen as a box, like text boxes or forms.

Current State

A search of the documentation revealed:

  • "in" terms: 395 occurrences across 147 files
  • "on" terms: 2,534 occurrences across 656 files

Proposed Changes

  1. Update the word list guidance to recommend "in" instead of "on" for UI elements
  2. Define exceptions where "on" should still be used:
    • Physical objects: "Use the arrow keys on your keyboard"
    • Potentially for overall pages: "On the Settings page" (though "In the Settings page" could work too)

Rationale

  • More intuitive for users ("in the GitLab UI" vs "on the GitLab UI")
  • Aligns with the new panel design being rolled out where UI areas have more defined, separate spaces
  • Simpler rule than Microsoft's complex guidance which distinguishes between starting points and secondary elements
  • Our left navigation is dynamic and not always the starting point like in Microsoft products

Related

Edited by 🤖 GitLab Bot 🤖